Migrating from ItemPath 2 to ItemPath 3

Updating from ItemPath 2 to ItemPath 3 is a special migration path. If you are updating from ItemPath 2 to a later version of ItemPath 2, use these instructions. If your software version is already ItemPath 3, update using these instructions.

Note: Before updating to version 3.0.0.0 and later, ensure you are running the latest version of ItemPath 2 (2.25.4.11). Follow these instructions to update to the latest version of ItemPath 2.

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. In the event of a firewall issue preventing this, please reach out to ItemPath support.
• Save the installer file on the ItemPath host.

In the instructions below, replace <target-version> with the ItemPath version being installed, such as 3.4.7. 

Follow These Steps to Migrate from ItemPath 2 to ItemPath 3

1. Make note of the current version of ItemPath installed in your environment
2. Install the Deployment Manager.

   1. Linux:

      bash install-deployment-manager.sh <target-version>

   2. Windows:

      cd $HOME
      .\Install-ItemPathDeploymentManager.cmd <target-version>

3. Bring the docker containers down by running the command: docker compose down
4. Run the Migration. The upgrade command will back up the current deployment and apply the ItemPath 3 migration.

   1. Linux:

      itempath-deploy upgrade <target-version>

   2. Windows:

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

5. 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.
6. Open your ItemPath application and confirm it loads as expected.

 

Rollback 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 migration 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.

Release Notes

Software release notes can be found online here.