1. Docs
    2. arrow-right
  2. On-Premise Installation - Windows
Matches version: 3.5.6

On-Premise Installation - Windows

If you plan on using the on-premise version of ItemPath, we recommend that you use a Linux server for best results.  Some customers have had success running ItemPath in a Windows desktop environment, though there are some notable differences in requirements and setup. This guide will cover installing and running ItemPath on a computer running Windows 11.

Please note that Docker Desktop is not officially supported for Windows Server and if you plan on running Docker and ItemPath from Windows Server, you will need to follow different installation steps for Docker.

Key terms

Before we get started, here are some key applications and terms in this installation guide:

  • Docker: See Why Docker? Docker is a platform for running applications through containers: a container includes everything the software needs to run and simplifies the process of getting software to run reliably without having to worry about the environment it’s running in.
  • Docker Compose: Docker Compose is a tool for defining and running Docker applications that link together multiple containers. It lets you describe these bundles in a YAML file and use that file to coordinate all of the interconnected containers.
  • Docker Engine: This is the part of Docker that does the heavy lifting. It’s an application that creates and manages containers, images, networks, and volumes. You can interact with it through either a command line interface (PowerShell) or through Docker Desktop.
  • Docker Desktop: This is an application that runs on desktop operating systems and allows you to build, run and manage Docker containers on your local machine. It bundles Docker Engine, Docker Compose, and the Docker command line interface (CLI) into a single application.
  • PowerShell: This is a command shell (CLI, scripting language, and automation management framework) for Windows. You may use a different command-line interface, but instructions in this document presume you are using PowerShell. If you are using a different terminal, some commands (e.g. mkdir) may be different.

Hardware Requirements

Our basic system requirements include:

  • A dedicated machine or virtual machine
  • A dual core CPU or greater
  • 4 GB RAM or greater
  • 50GB SSD or greater
  • Outbound Port 80/443 access for remote assistance, monitoring, and support of email outputs
  • A dedicated (not dynamic) IP address for the machine
  • VPN + SSH access to this machine

Software Requirements

Before we get to configuring Docker Desktop, you will need to configure Windows to meet Docker’s requirements. Your machine should be running a supported version of Microsoft Windows (e.g., Windows 11 Professional). Please note, we have not tested ItemPath’s compatibility with Windows on Arm.

Keep in mind the permission requirements for Docker on Windows. Ideally, Docker should be installed with administrative privileges, but it doesn't need to be run by an administrator.

  1. Install Windows Subsystem for Linux version 2 (WSL/WSL 2). This is ItemPath's recommended configuration for using Docker on Windows. For support with installing WSL, please see the official documentation. 
  2. Open a PowerShell terminal (as an administrator) and enter: wsl –install. This will install WSL with Ubuntu as the chosen distribution of Linux, though if you would like to use another version you are free to do so. We recommend following the Best practices for setting up a WSL development environment. Start WSL using Windows start menu, or from PowerShell with the command wsl. 

After installing and starting WSL, you can install Docker Desktop and configure it to use WSL.

Pre-Installation Checklist

Before being able to install ItemPath, you'll need a few things in place.

  • PPG SQL Server username, password, database name, dedicated IP address, and port number (if changed from the default port 1433).
  • PPG SQL Server will need to be able to accept remote connections via IP. The port should also be static, not dynamic. For more details on how to set this up, go here.

Initial setup

Once you’ve signed your purchase agreement, and ItemPath has processed your order, the ItemPath team will send you installation instructions, your license, two configuration files along with a username and password that will be needed during the install process:

  • Install-ItemPathDeploymentManager.cmd
  • Install-ItemPathDeploymentManager.ps1

Next, install Docker (if it isn't already available).

Installation via Docker

Docker is the recommended container solution for installing and running ItemPath, and can be broken down into a few simple steps:

  1. Confirm Docker 19 or greater is installed on the virtual machine by running docker version in the terminal. If Docker is not installed, instructions can be found here. 
  2. Required Post-Installation steps: Once Docker is installed, you must configure your Windows user to manage Docker without using sudo. This prevents file ownership conflicts when ItemPath creates its local database and log folders. Post-Installation steps can be found here.
  3. Install Docker Compose 2 or greater. Installation instructions can be found here.

Local Files

Once Docker and Docker Compose have been installed, you’ll want to take the installation files that were provided to you and put them in the local user directory (~/).

  1. Ensure that a local user exists with root permissions. Use this user to install and run ItemPath (not under sudo).
  2. Copy the file provided by the ItemPath team to the following locations:
    1. Add Install-ItemPathDeploymentManager.cmd and Install-ItemPathDeploymentManger.ps1 to your local user directory (~/).
  3. Run .\Install-ItemPathDeploymentManager.cmd -Version latest in PowerShell.

ItemPath Installation

Before you begin, check the latest release version here. 

  1. Log in to Docker to download the ItemPath images. To do this, run docker login.
  2. You'll be prompted to enter the username and password provided by ItemPath support.
  3. From the terminal, it’s time to download ItemPath. Navigate to the root  directory by typing cd ~. 
  4. Run ItemPath from the user directory (~/) by running this command from the terminal (NOTE: Replace [version number] with your desired version. Eg., 3.3.0): 
    itempath-deploy bootstrap [version number] --platform on-premise --yes

You can confirm ItemPath is running by visiting localhost in a browser, or by visiting the IP address of the host machine.

Install ItemPath without internet access

If you need to install ItemPath without a connection to the internet, please reach out to support@itempath.com for next steps.

ItemPath Startup & Shutdown

To start up ItemPath: Run ItemPath from the user directory (~/) by running from the terminal: .\itempath-deploy.cmd start.

To shut down ItemPath: Stop ItemPath from the user directory (~/) by running from the terminal: .\itempath-deploy.cmd stop.

To restart ItemPath: You can stop and restart ItemPath at the same time from the user directory (~/) by running from the terminal: .\itempath-deploy.cmd restart. This should stop ItemPath and all of its running containers, then relaunch each one.