Upgrade to Itential Platform 6.x

This guide shows you how to upgrade your Itential Platform installation.

Before you begin

Review the following resources before upgrading:

Platform 6 deprecations
Platform 6 breaking changes
Feature release and maintenance notes related to Platform 6

Contact your Itential Account Manager if you need help establishing an upgrade plan.

Choose your upgrade path

Select the upgrade path that matches your current installation:

Upgrade from Platform 6.x to newest version

This section explains how to upgrade from an earlier Platform 6 version to the latest Platform 6 release.

Prerequisites

Access to the Itential repository (contact your Itential Account Manager if needed)
Root or sudo access to your server
Review of release notes and dependency changes for the target version

Prepare for the upgrade

Before you upgrade, handle existing jobs and code:

Stop running jobs. Choose one of the following options:
- Verify that no active jobs are running in Operations Manager
- Disable task and job workers in Admin Essentials to prevent new jobs from starting, then wait several minutes for running tasks to complete
Verify custom code location. If your open-source or custom adapters and apps are in /opt/itential/platform/services or a custom directory, no action is needed. The upgrade updates only the server folder and continues to serve adapters and apps from the services directory.

Upgrade the platform

Download the latest Platform 6 Red Hat Package Manager (RPM) installation package from the Itential repository. To access the Itential repository:

If you have repository access, download the RPM directly from your organization's Itential repository portal
If you need access credentials, contact your Itential Account Manager
The RPM file is named itential-platform-6.x.x.rpm where 6.x.x is the version number

Copy the RPM to your server. We recommend using /tmp because it's a standard temporary directory accessible to all users:
```
cp itential-platform-6.x.x.rpm /tmp/
```
Verify the file is accessible by the service user. The installation package must be readable by the user that runs the itential-platform service.

To find the service user, use one of these methods:

Option 1: Check the service file
```
sudo systemctl status itential-platform
```
The output shows the service file location, typically /etc/systemd/system/itential-platform.service. Open the file to view the User parameter.

Option 2: Check the server directory
```
ls -la /opt/itential/platform/server
```
The owner shown is typically the service user.
Stop the itential-platform service:
```
sudo systemctl stop itential-platform
```

Run the upgrade:

rpm -Uh /tmp/itential-platform-6.x.x.rpm

The output shows the upgrade progress:

Preparing...                          ################################# [100%]
Updating / installing...
   1:itential-platform-6.x.x          ################################# [100%]

Start the itential-platform service:
```
sudo systemctl start itential-platform
```

Verify the upgrade was successful:

sudo systemctl status itential-platform

Successful output shows the service as active:

itential-platform.service - Itential Platform Service
     Loaded: loaded (/etc/systemd/system/itential-platform.service; enabled; vendor preset: disabled)
     Active: active (running) since Fri 2025-10-10 14:23:15 UTC; 5s ago
   Main PID: 12345 (node)
      Tasks: 23 (limit: 23449)
     Memory: 256.8M
     CGroup: /system.slice/itential-platform.service
             └─12345 node server.js

Upgrade from earlier versions

This section explains how to upgrade from Platform 2022.1, 2023.1, or 2023.2 to Platform 6.

Platform 6 organizes files differently than earlier versions. To avoid conflicts, Itential recommends installing Platform 6 on a new or clean system and moving your existing data to it, rather than upgrading your current installation directly.

Install Platform 6

Follow the Platform 6 installation instructions.

Migrate encrypted secrets

Platform 6 requires an encryption key for operation. Use the key migration utility to migrate encrypted secrets from your existing database.

Before you migrate

Complete the following tasks:

Back up your MongoDB database. The key migration utility connects to and modifies the database directly.
Back up your properties.json file (if used). The utility modifies encrypted values in place if the file contains $ENC encrypted secrets.
Prepare to migrate all collections at once. The utility cannot be run multiple times on a single database. If the migration is interrupted, restore from backup and run the utility again.

Run the migration utility

Navigate to the server directory:
```
cd /opt/itential/platform/server
```

Run the utility with your configuration. Replace $KEY with your encryption key:

Using a properties configuration file:

npm run key:migrate -- \
  --config-file /etc/itential/platform.properties \
  --encryption-key "$KEY"

Using a legacy properties.json file:

npm run key:migrate -- \
  --properties-json ./properties.json \
  --encryption-key "$KEY"

Using environment variables:

ITENTIAL_MONGO_URL=mongodb://127.0.0.1:27017 \
ITENTIAL_MONGO_DB_NAME=itential \
npm run key:migrate -- \
  --config-file /etc/itential/platform.properties \
  --encryption-key "$KEY"

(Optional) Migrate custom collections. If your organization uses custom collections with $ENC encrypted values, add the --extra-collections parameter:

npm run key:migrate -- \
  --encryption-key "$KEY" \
  --properties-json ./properties.json \
  --extra-collections custom-collection-1 \
  --extra-collections custom-collection-2

The utility migrates the following collections by default:

service_configs
oauth_clients
accounts
iap_profiles

Understand the output

The migration utility reports its progress as it runs. Example output:

> @itential/iap@6.0.0 key:migrate
> node utils/keyMigrate.js --encryption-key [KEY] --properties-json ./properties.json

Collection service_configs migrated document 1 with _id 67c07c608998f13133c9ba97 pointer /properties/properties/database/url
Collection service_configs: Successfully replaced 1 of 1 documents
Collection accounts migrated document 1 with _id 67c07c8da129bb3309dddbb3 pointer /gitTokens/GitHub
Collection accounts: Successfully replaced 1 of 1 documents
Decryption recheck validated -- key migration successful!

After the script completes successfully, you can connect Platform 6 to your existing database.

Migrate apps and adapters

Platform 6 stores custom applications and adapters in a different location than earlier versions. You need to copy your existing custom code to the new directory.

Default location

The default directory for custom apps and adapters is:

/opt/itential/platform/services

Custom location (optional)

By default, custom apps and adapters are stored in /opt/itential/platform/services. If you want to use a different location, you can specify it in one of three ways:

Add to your configuration file: Set the service_directory property in /etc/itential/platform.properties. For more information, see Platform Configuration.
Set an environment variable: Create an ITENTIAL_SERVICE_DIRECTORY environment variable on your system. For more information, see Platform Environment Variables.
Configure in Admin Essentials: Edit the serviceDirectory field in your active profile through the Itential Platform's Admin Essentials interface. For more information, see Profile Properties.

Copy your custom code

Locate your custom apps and adapters. Open-source adapters are installed at:
```
/opt/itential/current/node_modules/@itentialopensource
```
For organization-managed apps and adapters, consult your system administrator for the location.
Copy all custom apps and adapters to the Platform 6 services directory:
```
cp -r /path/to/custom/apps/* /opt/itential/platform/services/
```

Migrate properties

Platform 6 deprecates the properties.json configuration file. The platform supports configuration through:

platform.properties file: A configuration file stored in /etc/itential/ that contains settings like database connections, encryption keys, and custom directory paths
Environment variables: Environment variables - System-level settings that override file-based configuration

Platform 6 continues to support database profiles and the legacy properties.json file, but we recommend transitioning to environment variables or the platform.properties file.

Create your platform.properties file

Itential provides a template with example settings at:

/opt/itential/platform/server/utils/template.properties

Copy this template to create your configuration file:

sudo cp /opt/itential/platform/server/utils/template.properties /etc/itential/platform.properties

Continue using properties.json (not recommended)

To continue using a properties.json file, place it in:

/opt/itential/platform/server