> 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/configure/platform/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Configure Platform

> Understand how Platform 6 configuration works and choose the right approach

Itential Platform 6 simplifies configuration by letting you configure Itential Platform through environment variables or a platform configuration file and deploy as a container. This approach provides several benefits:

* **Consolidated startup configuration** — All startup configuration lives in a single location
* **User-defined environment variables** — Configure Platform 6 entirely through environment variables, including encryption keys
* **Intelligent default values** — Platform generates and pre-fills common default values when you don't fully configure your system
* **Hierarchical configuration** — Configure once and deploy to multiple locations
* **Default user** — Log in and configure Itential Platform without setting up Local AAA first

Platform 6 also improves the upgrade experience by reducing time and resource requirements. You define your own encryption key and provide it through environment variables or the properties file.

## Configuration files

In earlier Platform versions, configuration was split between a `properties.json` file and a MongoDB `profile`. Starting with Platform 6, you manage configuration primarily through environment variables or a `platform.properties` file. Configuration through `properties.json` is deprecated in Platform 6.

## Migrate from properties.json (earlier Platform versions)

Starting with Platform 6, the `bin` installer no longer copies the previous `properties.json` file. To migrate a `properties.json` file into a new `platform.properties` file, run this command:

```bash
npm run migrate:properties -- --json-file=<path> --out-file=<path>
```

The generated file includes commented-out defaults and descriptions for all excluded properties.

Supply Itential Platform with a `platform.properties` file (or a `properties.json`) using the `--config-file=<path>` launch option. If you don't provide a `--config-file` argument, Itential Platform looks in these locations:

1. `/etc/itential/platform.properties`
2. Platform installation directory for a `properties.json`

If neither file exists, Platform uses defaults for all configurations not defined by environment variables.

In Platform 6, use profiles only for configurations that change while the server runs, such as `prebuiltProps`.

## Priority order

When you provide conflicting configuration properties, Platform resolves them in this priority order:

1. Environment variable (highest priority)
2. `platform.properties` configuration file
3. Profile
4. Default value (lowest priority)

This hierarchy lets you create a reusable configuration file and override specific properties with environment variables for deployment.

## View your configuration

To view the current configuration:

1. Go to **Itential Platform → Admin Essentials → Configuration**
2. View all configuration properties, their values, and their origins

## File format differences

The following examples show the file format differences between Platform versions.

### Platform 6 (platform.properties)

```properties
# My Comment
service_directory = dev/services
mongo_db_name = platform6
log_directory = dev
webserver_log_directory = dev
auth_admin_groups = [{"provenance":"Local AAA","group":"pronghorn_admin"}]
encryption_key = 74b589bce5a0aaae1d45f13479208f34f5eb0458bde7fb81a2f26ee8d61fae37
```

### Platform 6 (environment variables)

```bash
export ITENTIAL_SERVICE_DIRECTORY="dev/services"
export IAP_MONGO_DB_NAME=platform6
export IAP_LOG_DIRECTORY=dev
export IAP_WEBSERVER_LOG_DIRECTORY=dev
export IAP_AUTH_ADMIN_GROUPS='[{"provenance":"Local AAA","group":"pronghorn_admin"}]'
export IAP_ENCRYPTION_KEY=74b589bce5a0aaae1d45f13479208f34f5eb0458bde7fb81a2f26ee8d61fae37
```

### Platform 23.2 and earlier (properties.json)

Profiles also use this format.

```json
{
  "serviceDirectory": "dev/services",
  "mongoProps": {
    "db": "platform6"
  },
  "loggerProps": {
    "log_directory": "dev",
    "webserver": {
      "log_directory": "dev"
    }
  },
  "authenticationProps": {
    "admins": [
      {
        "provenance":"Local AAA",
        "group":"pronghorn_admin"
      }
    ]
  },
  "encryptionKey": "74b589bce5a0aaae1d45f13479208f34f5eb0458bde7fb81a2f26ee8d61fae37"
}
```

## Configure a default admin user

Platform 6 enables a default user account to log in and configure AAA adapters through Admin Essentials. This eliminates the need to install an AAA adapter before using Platform.

Configure the default user with these variables:

| platform.properties     | Environment Variable             | Type    |
| :---------------------- | :------------------------------- | :------ |
| `default_user_enabled`  | `ITENTIAL_DEFAULT_USER_ENABLED`  | Boolean |
| `default_user_username` | `ITENTIAL_DEFAULT_USER_USERNAME` | String  |
| `default_user_password` | `ITENTIAL_DEFAULT_USER_PASSWORD` | String  |

Use the default user to set up the first admin account. After you enable any AAA/SSO adapter, the default user can't log in. Restart Platform after configuring AAA/SSO adapters.

## Known limitations

* **Profile access** — Profiles are only accessible after connecting to MongoDB. You can't define MongoDB-related configuration (including encryption) within a Profile
* **Stateful properties** — Configuration settings that capture Platform state must only exist in a Profile document. As of Platform 6, the only stateful property is `prebuiltProps`
* **API deprecation** — The `switchActiveProfile` API is deprecated. You can only switch profiles when Platform is configured with a deprecated `properties.json` file
* **Configuration reload** — Platform reads environment variables and config files only at startup. You must restart Platform to apply configuration changes
* **File modifications** — Platform never automatically modifies your `platform.properties` file or environment variables. You must make changes outside Platform
* **Default user restrictions** — The default user can only log in before you configure any AAA/SSO adapter. After a qualifying adapter runs, Platform won't accept new logins by the default user (though active sessions may continue)
* **Single configuration file** — You can only supply one configuration file to Platform. If both `/etc/itential/platform.properties` and a legacy `properties.json` exist in the installation directory (and you don't supply a `--config-file` option), Platform only uses the `platform.properties` file

If you encounter issues during configuration or need support, contact the Itential Service Desk through the [Customer Portal](https://itential.atlassian.net/servicedesk/customer/portals).

## Related reading

* [Installation](/itential-platform/install/platform)
* [Upgrading](/maintain/upgrade)
* [Adapters & Custom Apps](/itential-platform/install/apps-adapters)

> Understand how Platform 6 configuration works and choose the right approach