Upgrade to the latest version of Platform 6

Upgrade your Itential Platform installation to the latest version. This guide covers upgrades within Platform 6 and migrations from earlier platform versions (2022.1, 2023.1, 2023.2) to the latest version of Platform 6.

Before you begin

Review these resources before upgrading:

Choose your upgrade path

Upgrade within Platform 6

Upgrade from an earlier Platform 6 version to the latest Platform 6 release.

Prerequisites

• Repository access — Access to the Itential repository (contact your Itential Account Manager if needed).
• Server access — Root or sudo access to your server.
• Release review — Review release notes and dependency changes for the target version.
• Backup — Back up your MongoDB database and configuration files.

Prepare for upgrade

$
mongodump --db=itential --out=/backup/mongodb/$(date +%Y%m%d)

$
sudo cp /etc/itential/platform.properties /backup/platform.properties.$(date +%Y%m%d)

Download the installation package

$
cp itential-platform-6.x.x.rpm /tmp/

$
ls -la /tmp/itential-platform-6.x.x.rpm

Find the service user

The installation package must be readable by the user that runs the itential-platform service.

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.

Run the upgrade

$
sudo systemctl stop itential-platform

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

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

$
sudo systemctl start itential-platform

$
sudo systemctl status itential-platform

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

Troubleshoot upgrade issues

If the upgrade fails or the service does not start:

$
sudo journalctl -u itential-platform -n 100

$
tail -f /var/log/itential/app.log

$
ls -la /opt/itential/platform

$
sudo systemctl status mongod

Migrate to Platform 6

Migrate from Platform 2022.1, 2023.1, or 2023.2 to Platform 6.

Migration overview

The migration process involves:

1. Installing Platform 6 on a new or clean system.
2. Migrating encrypted secrets from your existing database.
3. Migrating custom apps and adapters.
4. Migrating configuration settings.

Install Platform 6

After installation, proceed with data migration.

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

Run the key migration utility

$
cd /opt/itential/platform/server

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

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

$
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"

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

Migrated collections

The utility migrates these collections by default:

• service_configs — Service configuration data
• oauth_clients — OAuth client credentials
• accounts — User account information
• iap_profiles — Platform profiles

Understand migration output

The migration utility reports 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!

Success indicators:

• Each collection shows “Successfully replaced X of X documents.”
• Final message: “Decryption recheck validated — key migration successful!”

After successful migration, 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.

Platform 6 default location:

/opt/itential/platform/services

Earlier versions location:

/opt/itential/current/node_modules/@itentialopensource

Configure a custom location (optional)

Option 1: Configuration file

Set the service_directory property in /etc/itential/platform.properties:

1
service_directory=/custom/path/to/services

Option 2: Environment variable

$
export ITENTIAL_SERVICE_DIRECTORY=/custom/path/to/services

Option 3: Admin Essentials

Edit the serviceDirectory field in your active profile through Admin Essentials.

Copy custom code

$
cp -r /path/to/custom/apps/* /opt/itential/platform/services/

$
sudo chown -R <service-user>:<service-group> /opt/itential/platform/services

$
sudo systemctl restart itential-platform

Migrate configuration

Platform 6 deprecates the properties.json configuration file and introduces new configuration methods.

Configuration options in Platform 6

Create the platform.properties file

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

$
sudo vi /etc/itential/platform.properties

1
mongo.url=mongodb://127.0.0.1:27017
2
mongo.db_name=itential

1
encryption.key=your-encryption-key-here

1
service_directory=/custom/path/to/services

$
sudo chown <service-user>:<service-group> /etc/itential/platform.properties
$
sudo chmod 600 /etc/itential/platform.properties

Continue using properties.json (not recommended)

If you must continue using properties.json, place it in the Platform 6 server directory:

$
cp properties.json /opt/itential/platform/server/

Verify the migration

$
sudo systemctl start itential-platform

$
sudo systemctl status itential-platform

$
tail -f /var/log/itential/app.log

Troubleshoot migration issues

Database connection fails

$
sudo systemctl status mongod

$
mongo mongodb://127.0.0.1:27017/itential

Custom apps or adapters not loading

$
ls -la /opt/itential/platform/services

$
sudo chown -R <service-user>:<service-group> /opt/itential/platform/services

$
grep -i error /var/log/itential/app.log

Encryption errors

Post-upgrade tasks

Update documentation

• Record the new platform version.
• Update system documentation.
• Document any configuration changes.
• Note any custom code modifications required.

Test functionality

• Run existing workflows.
• Test adapter connections.
• Verify integrations.
• Check custom apps and automations.
• Review scheduled jobs.
• Test user access and permissions.

Monitor performance

• Check resource utilization (CPU, memory, disk).
• Review log files for errors or warnings.
• Monitor database performance.
• Verify workflow execution times.
• Check adapter response times.

Clean up

• Delete temporary RPM files.
• Archive old backups.
• Clean up migration utility output.
• Remove deprecated configuration files after verification.

Best practices

Before upgrading:

• Always back up your database and configuration.
• Review release notes and breaking changes.
• Test the upgrade in a non-production environment first.
• Schedule upgrades during maintenance windows.
• Stop active jobs to prevent data loss.

During the upgrade:

• Follow the appropriate upgrade path for your version.
• Verify each step completes successfully before proceeding.
• Monitor logs for errors or warnings.
• Keep backup accessible for quick rollback if needed.

After the upgrade:

• Thoroughly test all functionality.
• Monitor performance and logs.
• Update documentation.
• Communicate upgrade completion to stakeholders.
• Plan for cleanup of old files and backups.

For migrations to Platform 6:

• Use a clean system when possible.
• Migrate encrypted secrets before connecting to the database.
• Verify custom code compatibility.
• Transition to platform.properties or environment variables.
• Test thoroughly before decommissioning the old system.

Next steps