Updating ItemPath (ItemPath 3)

ItemPath updates do not install automatically. Use the itempath-deploy utility to check the current version, apply the target version, and confirm the update completed.

Note: These instructions are for updates from ItemPath from 3.0.0 to later versions. If you are updating from ItemPath 2 to ItemPath 3, use these instructions instead.

Before You Start

• Docker must be installed and running.
• Docker Compose v2 must be available through docker compose.
• The Docker engine must run Linux containers.
• The operator must have permission to run Docker commands.
• The host must be able to pull ItemPath images from the registry, unless the images are already loaded locally.
• Save the installer file on the ItemPath host.

Replace <target-version> with the ItemPath version being installed, such as 3.3.1. 

Follow These Steps to Perform the Update

Step 1: Make note of the current version of ItemPath installed in your environment

Step 2: Follow the instructions to Install the Deployment Manager.

Step 3: Confirm the Deployment Manager is installed and that the current version is the expected ItemPath 2 version (noted in step 1) before continuing.

Linux (Custom Root):

itempath-deploy status

Windows (Custom Root):

cd $HOME
.\itempath-deploy.cmd status

Step 4: Bring the docker containers down by running the command: docker compose down

Step 5: Apply the Update. The upgrade command will back up the current deployment and apply the update to the specified version.

Linux (Custom Root):

itempath-deploy upgrade <target-version>

Windows (Custom Root):

cd $HOME
.\itempath-deploy.cmd upgrade <target-version>

Step 6: If prompted INSTALL_TYPE is not set in .env. Is this a cloud or on premise install? enter on premise. Follow any additional confirmation prompts that appear.

Step 7: Confirm that the current version is now the specified version of ItemPath 3. 

Linux (Custom Root):

itempath-deploy status

Windows (Custom Root):

cd $HOME
.\itempath-deploy.cmd status

Step 8: Open your ItemPath application and confirm it loads as expected.

Roll Back the Update

If for any reason, you need to roll back from the ItemPath 3 upgrade, use the following command to restore the earlier deployment state of ItemPath 2.

Linux: 

itempath-deploy rollback

Windows: 

cd $HOME
.\itempath-deploy.cmd rollback

Note: the rollback command does not preserve changes made after the migration. It will restore the backup of your environment prior to the upgrade.

What Not To Do

• Do not manually edit ItemPath deployment files.
• Do not stop, start, or update ItemPath with manual Docker commands as the update path.
• Do not move or delete ItemPath data while updating.
• Do not remove deployment backups unless support confirms it is safe.
• Do not roll back without understanding that changes made after the migration will be discarded.
• Do not assume $HOME is the deployment root on Windows unless support confirms it.

Release Notes

Software release notes can be found online here.