> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-platform/6/maintain/upgrade/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.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

**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.

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

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.

#### Before you migrate

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

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

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

> How to upgrade within Platform 6 or migrate from Platform 2022.1, 2023.1, or 2023.2 to the latest version of Platform 6.