Configure Platform

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

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:

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

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)

1
# My Comment
2
service_directory = dev/services
3
mongo_db_name = platform6
4
log_directory = dev
5
webserver_log_directory = dev
6
auth_admin_groups = [{"provenance":"Local AAA","group":"pronghorn_admin"}]
7
encryption_key = 74b589bce5a0aaae1d45f13479208f34f5eb0458bde7fb81a2f26ee8d61fae37

Platform 6 (environment variables)

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

1
{
2
  "serviceDirectory": "dev/services",
3
  "mongoProps": {
4
    "db": "platform6"
5
  },
6
  "loggerProps": {
7
    "log_directory": "dev",
8
    "webserver": {
9
      "log_directory": "dev"
10
    }
11
  },
12
  "authenticationProps": {
13
    "admins": [
14
      {
15
        "provenance":"Local AAA",
16
        "group":"pronghorn_admin"
17
      }
18
    ]
19
  },
20
  "encryptionKey": "74b589bce5a0aaae1d45f13479208f34f5eb0458bde7fb81a2f26ee8d61fae37"
21
}

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 the platform GUI.

Configure the default user with these variables:

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

Related reading

• Installation
• Upgrading
• Adapters & Custom Apps