On-Premises Installation - Windows

If you plan on using the on-premises 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.

Key terms

Before we get started, here are some key applications and terms we’ll be using 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. 
• 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.

Windows prerequisites

Our basic system requirements include:

• A dedicated machine or virtual machine (preferably Ubuntu Linux)
• 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

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.

First, install Windows Subsystem for Linux version 2 (WSL2). This our recommended configuration for using Docker on Windows. For support with installing WSL2, please see the official documentation. Hyper-V will also work with Docker Desktop, and can be used instead of WSL2.  To get started quickly, 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 WSL2 using Windows start menu, or from PowerShell with the command wsl. 

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

Create ItemPath folders

In all instructions that follow, terms included in square brackets are placeholders for words determined by your system, replace any commands or directories as needed. To begin with, you’ll need to set up the directories that ItemPath will use:

1. Create the following folders in your user (C:/Users/[Name]) directory:
   1. ItemPath
   2. ItemPath/data
   3. ItemPath/files
2. Copy the files provided by ItemPath’s Support Team to the appropriate folders: 
   1. Add docker-compose.yml to C:/Users/[Name]
   2. Add appdata.db to C:/Users/[Name]/ItemPath/data

Install ItemPath with PowerShell

With folders created, the quickest way to install and configure ItemPath is through your PowerShell terminal.

1. Navigate to your local user directory: C:\Users\[Name]
2. Ensure that WSL2 is running:
   1. In your PowerShell terminal, enter: wsl
   2. Your terminal prompt will shift to: [username]@[linuxname]:/mnt/c/Users/[Name]$. Enter the command exit to return to your Windows PowerShell prompt, WSL will be running in the background.
3. Ensure that Docker Desktop installed the Docker CLI tools. 
   1. Run docker -v
   2. Run docker-compose -v. Depending on your version of Docker, you may need to use the command docker compose -v, if so, use docker compose instead of docker-compose.
4. Login with the username and password supplied to you by the ItemPath support team: docker login -u [username] -p [password].
5. Run docker-compose pull. Docker Compose will use the contents of the docker-compose.yml to download and install the necessary files for running ItemPath.
6. After Docker Compose finishes downloading the files, you’ll be ready to start ItemPath. You can start the container from PowerShell with the command: docker-compose up -d

Congratulations! ItemPath will be running in a container on your computer. ItemPath will now be available in Docker Desktop as one of the containers running on your system. You can start and stop ItemPath using Docker Desktop, as well as review logs, volumes, and port mappings. For more information about how to use Docker Desktop, please visit Docker Desktop’s manual. To access ItemPath's starting screen, open your browser and enter localhost into your browser’s address bar.

Install ItemPath without internet access

If you need to install ItemPath without a connection to the internet,  our team should have provided you with an archive (compressed collection of files). You can then use the command docker load < itempath_api.tar to install ItemPath from the archive.

Install ItemPath with Docker Desktop

If you prefer, you could complete the installation using Docker Desktop. On Windows, Docker Desktop includes a functioning terminal that runs Power Shell. The only difference in the procedure is that you will need to sign in to Docker Desktop with the credentials supplied by the ItemPath team instead of your personal login.

After you have signed-in, open the Terminal in Docker Desktop. You can then use PowerShell to complete the steps from the PowerShell installation process described above. If you encounter an error message that reads: “requested access to the resource is denied” you will need to login with the credentials supplied by ItemPath.

Once you've installed ItemPath, you can switch back to your regular login in Docker Desktop.

Troubleshooting

 

System cannot find the file specified

Error messages that contain “System cannot find the file specified" indicate that something is unavailable in your Docker Desktop configuration. For example: 

unable to get image 'ppgsupport/api': error during connect: Get "http://%2F%2F.%2Fpipe%2FdockerDesktopLinuxEngine/v1.47/images/ppgsupport/api/json": open //./pipe/dockerDesktopLinuxEngine: The system cannot find the file specified.

Indicates a problem with your Linux engine configuration. Verify that you have correctly installed WSL2 or Hyper-V, and configured Docker to use the back-end you have installed. If you are using WSL2, ensure that it is running.

Image operating system “linux” cannot be used on this platform

This error message occurs when Docker is attempting to use a container type that is not available. Ensure that you have configured Docker to use Linux containers (ItemPath is not compatible with Windows containers). Verify that you have correctly installed WSL2 or Hyper-V, and configured Docker to use the back-end you have installed. If you are using WSL2, ensure that it is running.

Access denied

If you encounter an error while running docker compose, that includes the message “access denied” or “requested resources is unavailable”,  ensure that you are logged in with the credentials provided by ItemPath’s support team. In your command line, enter docker logout then docker login -u [username] -p [password] (replacing username and password with your credentials).