On-Premises Installation - Linux

ItemPath is available as an on-premises application that can be installed and run on a server owned and operated by your company. 

The main reason for doing this is improved security by running ItemPath inside of your network. Doing this comes with drawbacks in terms of the level of support ItemPath can provide: you may need to provide ItemPath with the ability to remotely connect to your server running ItemPath for support and you will be responsible for conducting your own installation. The ItemPath team can perform updates if provided with remote access to the machine.

If you have purchased the on-premises version of ItemPath, using a Linux server is strongly recommended, though ItemPath also supports installation onto Windows desktop. Windows Server is not officially supported (it doesn't support Docker Desktop, though some customers have reported success installing into Windows Server).

Hardware requirements

• A dedicated machine or virtual machine (preferably Ubuntu Linux)
• Ubuntu Linux 18 or greater (UI Linux isn't required)
• 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 and SSH access to this machine, with a local user with admin permissions

Software requirements

ItemPath must be run from a container: 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. See Why Docker for more information about using containers.

• Docker Engine 19 or greater and Docker Compose 1.22 or greater.
• OR Podman 3.4 or greater, with podman-docker, podman-plugins, and docker-compose installed.

ItemPath team access

Remote support for ItemPath can be easier if you provide the ItemPath team with remote access to your installation. If you would like to have ItemPath staff perform updates or access your system for support, we recommend that you provide:

• Remote connection information (VPN, SSH, TeamViewer)
• Username and password for the machine (ideally with local root access)

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, and two configuration files that will be needed during the install process:

• docker-compose.yml — this will store all the boot-up procedures for ItemPath, including running the web server, API, and other services
• appdata.db — this is the initial internal database for ItemPath, storing users, reports, settings, and other data

Before installation, you will need to do some initial configuration for your server:

1. Ensure that a local user exists with root/sudo permissions, that will install and run ItemPath.
2. Create the following folders in your user (~/) directory and adjust the permissions for each so the user has read/write access:
   • ItemPath
   • ItemPath/data
   • ItemPath/files
3. Copy the files provided by the ItemPath team to the following locations:
   • Add docker-compose.yml to your local user directory (~/).
   • Add appdata.db to ~/ItemPath/data

Next, install Docker (if it isn't already available). If you prefer Podman, it can also install and run ItemPath.

Installation via Docker (Recommended)

Docker is the recommended container solution for installing and running ItemPath. Start by installing Docker. You will need both Docker Engine and Docker Compose installed. Docker Engine creates and manages containers, images, network information, and volume information. Docker Compose installs various dependencies required by your application. Perform these post-installation steps to ensure that Docker will run correctly.

Next verify that you have correctly completed the Docker installation:

• Confirm that Docker 19 or greater is installed by running docker -version. If not, follow these steps.
• Confirm that Docker Compose version 1.22 or greater is installed. If not, follow these instructions.

If your server is connected to the internet, you can use Docker Hub to download and install ItemPath: Run docker login and enter the username and password provided to you by ItemPath’s support team.

Note: If you’d like to lock ItemPath to a specific version, you can tag the images in the docker-compose.yml file with the version number you would like to install. See this guide to learn how.

From the terminal, it's time to download ItemPath. Navigate to the directory containing the docker-compose.yml file by typing cd ~. Then, download ItemPath using the command docker compose pull (or docker-compose pull, depending on your version of Docker Compose).

If you need to install ItemPath without a connection to the internet, the ItemPath team can provide 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.

Installation via Podman

Installing ItemPath using Podman is a supported alternative and requires a few additional steps:

1. Create a local user with root/sudo permissions.
2. Confirm Podman 3.4 or greater is installed on the virtual machine.
3. Make sure podman-docker, podman-plugins and docker-compose packages are installed using: sudo yum install -y podman-docker docker-compose podman-plugins
4. Confirm the Podman socket is running by running:
   • sudo systemctl enable podman.socket
   • sudo systemctl start podman.socket
   • sudo systemctl status podman.socket
5. Add the docker host variable by running: export DOCKER_HOST=unix:///run/user/$UID/podman/podman.soc

You can familiarize yourself with Podman through their documentation. 

This is an officially supported alternative to Docker and if you have further questions, don’t hesitate to reach out to the ItemPath Support team. If you use the podman-docker package, you should be able to follow the installation guide using Docker commands. The package will alias Docker commands to equivalent commands for Podman.

ItemPath startup and shutdown

To start up ItemPath

Run ItemPath from the user directory (~/) by running from the terminal: docker compose up -d. This should start ItemPath and any of its running containers (previous versions of Docker Compose may require docker-compose up -d).

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

To shut down ItemPath

Stop ItemPath from the user directory (~/) by running from the terminal: docker compose down (previous versions may require docker-compose down). This will stop ItemPath and any associated containers.

To restart ItemPath

You can stop and restart ItemPath at the same time from the user directory (~/) by running from the terminal: docker compose down && docker compose up -d (previous versions of Docker Compose may require docker-compose down && docker-compose up =d). This should stop ItemPath and any associated containers, then relaunch each one.