> This page is for Itential Platform On-Prem, version 6 (default).
> For other versions, use one of these documentation indexes:
> - 6 (default): https://docs-test.itntl.com/itential-platform/6/llms.txt
> - 2023.2: https://docs-test.itntl.com/itential-platform/2023-2/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-test.itntl.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-test.itntl.com/_mcp/server.

# Upgrade to the latest version of Platform 6

> How to upgrade within Platform 6 or migrate from Platform 2022.1, 2023.1, or 2023.2 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:

#### [Platform 6 deprecations](/itential-platform/release-notes/deprecations/overview)

Features and APIs removed in Platform 6

#### [Platform 6 breaking changes](/itential-platform/release-notes/breaking-changes/overview)

Changes that may impact your installation

#### [Feature release announcements](/itential-platform/release-notes/feature-announcements/600)

New features in Platform 6 releases

#### [Maintenance release notes](/itential-platform/release-notes/changelog)

Bug fixes and improvements

> **Info**
>
> **Need help?** Contact your Itential Account Manager for assistance establishing an upgrade plan.

## Choose your upgrade path

| Current version                    | Target version    | Upgrade path                                            |
| ---------------------------------- | ----------------- | ------------------------------------------------------- |
| Platform 6.x.x                     | Latest Platform 6 | [Upgrade within Platform 6](#upgrade-within-platform-6) |
| Platform 2022.1, 2023.1, or 2023.2 | Platform 6        | [Migrate to Platform 6](#migrate-to-platform-6)         |

---

## 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

#### Stop running jobs

Choose one of these options:

**Option 1: Verify no jobs are running**

* Check Operations Manager for active jobs.
* Wait for all jobs to complete.

**Option 2: Disable new jobs**

* Disable task and job workers in Admin Essentials.
* Wait several minutes for running tasks to complete.

#### Verify custom code location

Confirm your custom code location:

* **Default location:** `/opt/itential/platform/services`
* **Custom location:** Check your configuration.

The upgrade updates only the server folder and continues to serve adapters and apps from the services directory.

> **Info**
>
> If you're upgrading to Platform 6.6.0 or later, upgrade your host to Node 22 if you install the RPM (Platform images bundle Node 22), and check any custom apps or adapters against Node 22 before you upgrade. See [Node.js runtime upgraded to Node 22](/itential-platform/release-notes/breaking-changes/node-22-runtime-upgrade).

#### Back up the database

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

#### Back up configuration

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

### Download the installation package

#### Access the repository

Download directly from your organization's Itential repository portal. If you need credentials, contact your Itential Account Manager.

#### Download the RPM

Download the RPM file named `itential-platform-6.x.x.rpm`, where `6.x.x` is the target version number.

#### Copy to the server

Copy the RPM to your server. Use `/tmp` as it is accessible to all users:

```bash
cp itential-platform-6.x.x.rpm /tmp/
```

#### Verify file permissions

Ensure the file is readable by the service user:

```bash
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**

```bash
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**

```bash
ls -la /opt/itential/platform/server
```

The owner shown is typically the service user.

### Run the upgrade

#### Stop the Platform service

```bash
sudo systemctl stop itential-platform
```

#### Install the new version

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

The output shows progress:

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

#### Start the Platform service

```bash
sudo systemctl start itential-platform
```

#### Verify the upgrade

Check that the service started successfully:

```bash
sudo systemctl status itential-platform
```

A successful result 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
```

#### Verify in the UI

Log in to the Platform UI and verify:

* Platform is accessible.
* Version number is correct (check Admin Essentials).
* Workflows and automations function properly.

### Troubleshoot upgrade issues

If the upgrade fails or the service does not start:

#### Check service logs

```bash
sudo journalctl -u itential-platform -n 100
```

#### Check platform logs

```bash
tail -f /var/log/itential/app.log
```

#### Verify file permissions

```bash
ls -la /opt/itential/platform
```

#### Check the database connection

```bash
sudo systemctl status mongod
```

#### Restore from backup if needed

If the upgrade cannot be resolved, restore from backup and contact Itential Support.

---

## Migrate to Platform 6

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

> **Warning**
>
> Platform 6 organizes files differently than earlier versions. To avoid conflicts, Itential recommends installing Platform 6 on a new or clean system and migrating your data, rather than upgrading your current installation directly.

### 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

#### [Platform 6 installation guide](/itential-platform/install/platform)

Follow the complete Platform 6 installation instructions

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. To replace the encryption key on an existing Platform 6 installation, [rotate the encryption key](/itential-platform/6/maintain/rotate-encryption-key) instead.

#### Before you migrate

> **Warning**
>
> **Critical prerequisites:**
>
> * Back up your MongoDB database — the utility modifies the database directly.
> * Back up your `properties.json` file — the utility modifies encrypted values in place.
> * Prepare to migrate all collections at once — the utility cannot be run multiple times on a single database.
>
> If migration is interrupted, restore from backup and run the utility again.

#### Run the key migration utility

#### Navigate to the server directory

```bash
cd /opt/itential/platform/server
```

#### Choose a configuration method

Select the method that matches your setup:

**Method 1: Using platform.properties file**

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

**Method 2: Using legacy properties.json file**

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

**Method 3: Using environment variables**

```bash
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"
```

Replace `$KEY` with your encryption key.

#### Migrate custom collections (optional)

If you have custom collections with encrypted values:

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

#### Review the output

Verify the migration completed successfully by checking the output.

#### 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`:

```properties
service_directory=/custom/path/to/services
```

**Option 2: Environment variable**

```bash
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

#### Locate custom code

Find your custom apps and adapters:

* **Open-source adapters:** `/opt/itential/current/node_modules/@itentialopensource`
* **Organization-managed code:** Consult your system administrator.

#### Copy to Platform 6

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

#### Set file ownership

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

#### Verify the migration

Restart Platform and verify custom apps and adapters load correctly:

```bash
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

| Method                       | File location                       | Recommended | Notes                                |
| ---------------------------- | ----------------------------------- | ----------- | ------------------------------------ |
| **platform.properties file** | `/etc/itential/platform.properties` | Yes         | Preferred method for Platform 6      |
| **Environment variables**    | System environment                  | Yes         | Override file-based configuration    |
| **Database profiles**        | MongoDB                             | Legacy      | Supported for backward compatibility |
| **properties.json file**     | `/opt/itential/platform/server`     | No          | Deprecated, not recommended          |

> **Info**
>
> Platform 6 continues to support database profiles and the legacy `properties.json` file, but Itential recommends transitioning to environment variables or the `platform.properties` file.

#### Create the platform.properties file

#### Copy the template

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

#### Edit the configuration

```bash
sudo vi /etc/itential/platform.properties
```

#### Set the database connection

```properties
mongo.url=mongodb://127.0.0.1:27017
mongo.db_name=itential
```

#### Set the encryption key

```properties
encryption.key=your-encryption-key-here
```

#### Configure a custom service directory (optional)

```properties
service_directory=/custom/path/to/services
```

#### Set file permissions

```bash
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:

```bash
cp properties.json /opt/itential/platform/server/
```

> **Warning**
>
> The `properties.json` file is deprecated. Migrate to `platform.properties` or environment variables for better security and maintainability.

### Verify the migration

#### Start Platform

```bash
sudo systemctl start itential-platform
```

#### Check service status

```bash
sudo systemctl status itential-platform
```

#### Access the UI

Log in to the Platform UI and verify:

* Platform is accessible.
* Version shows Platform 6.x.x.
* All expected apps and adapters are loaded.

#### Test workflows

* Execute existing workflows.
* Test adapter connections.
* Verify data access.

#### Review logs

```bash
tail -f /var/log/itential/app.log
```

### Troubleshoot migration issues

#### Database connection fails

#### Verify MongoDB is running

```bash
sudo systemctl status mongod
```

#### Verify the connection string

Check the MongoDB URL in your configuration.

#### Test the connection

```bash
mongo mongodb://127.0.0.1:27017/itential
```

#### Check the firewall

If using a remote database, ensure the firewall allows MongoDB connections.

#### Custom apps or adapters not loading

#### Verify file location

```bash
ls -la /opt/itential/platform/services
```

#### Check file permissions

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

#### Review logs

```bash
grep -i error /var/log/itential/app.log
```

#### Verify compatibility

Ensure custom code is compatible with Platform 6.

#### Encryption errors

#### Verify key migration completed successfully

Confirm the key migration utility ran without errors.

#### Check the encryption key

Verify the encryption key in your configuration matches the key used for migration.

#### Review migration output

Check the migration utility output for errors or skipped collections.

#### Re-run the migration

If needed, restore the database backup and re-run the migration utility.

---

## 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

#### [Platform 6 documentation](/itential-platform/overview)

Learn about Platform 6 features and capabilities

#### [Configure platform settings](/itential-platform/configure/platform)

Configure Platform 6 for your environment

#### [Admin Essentials](/itential-platform/admin-essentials/overview)

Manage platform settings and profiles

#### [Archive and purge data](/itential-platform/maintain/archive-purge-data)

Implement data retention policies