Deploy with containers

Itential provides pre-built OCI-compliant images of Platform 6 hosted on the Itential Docker registry. Containers are well-suited for development environments and teams using Docker-based workflows.

Containerization offers the following advantages over a traditional server deployment:

Benefit	Description
Horizontal scaling	Additional Platform containers can be created and destroyed according to workload demands
Deployment automation	Containers can be deployed dynamically without manual intervention
Fault tolerance	Containers can substitute for one another in the event of a failure
Blue-green deployment	Environment upgrades can be completed with minimal production downtime
Hybrid deployments	Platform containers integrate with both on-premise and cloud-based resources

This guide covers Docker. Detailed instructions for Docker Compose and Kubernetes fall outside its scope. Example Docker Compose files are available in the Itential open source repository.

Before you begin

Container runtime

Platform images are compliant with Open Container Initiative (OCI) specifications. This guide assumes Docker as the container runtime.

Registry access

Platform images are hosted on the Itential Docker registry. Contact your Itential Account Manager to obtain:

Access key ID
Secret access key
Bundle name

AWS CLI

The AWS Command Line Interface (AWS CLI) must be installed on your host OS to authenticate with the Itential registry.

Log in to the registry

Authenticate with the Itential Docker registry before pulling or running images.

$ export AWS_ACCESS_KEY_ID=<access_key_id>
$ export AWS_SECRET_ACCESS_KEY=<secret_access_key>
$ 
$ aws ecr get-login-password --region us-east-2 \
>   | docker login --username AWS --password-stdin 497639811223.dkr.ecr.us-east-2.amazonaws.com

Replace <access_key_id> and <secret_access_key> with the credentials provided by your Itential Account Manager.

Pull a Platform image

$ docker pull 497639811223.dkr.ecr.us-east-2.amazonaws.com/<bundle_name>:<tag>

Replace <bundle_name> with your bundle name and <tag> with the desired Platform version, for example 6.0.2.

Referencing a feature release tag such as 6.0.0 pulls the latest maintenance build of that version, which may change over time. In production environments, always pin to a specific maintenance release tag such as 6.0.2.

Start a container

The minimum required configuration is an encryption key. Pass it using the -e flag.

$ docker run -d -p 3000:3000 -p 3443:3443 \
>   -e ITENTIAL_ENCRYPTION_KEY="<encryption_key>" \
>   497639811223.dkr.ecr.us-east-2.amazonaws.com/<bundle_name>:<tag>

For information on generating an encryption key, see Install Platform 6.

Configure with environment variables

All Platform configuration properties can be set using environment variables with the ITENTIAL_ prefix. Pass each variable using the -e flag.

$ docker run -d -p 3000:3000 -p 3443:3443 \
>   -e ITENTIAL_SERVER_ID="server1" \
>   -e ITENTIAL_ENCRYPTION_KEY="<encryption_key>" \
>   497639811223.dkr.ecr.us-east-2.amazonaws.com/<bundle_name>:<tag>

For the full list of available properties and their environment variable equivalents, see Platform properties reference.

Generate an encrypted value

To generate an encrypted value from inside the container — for example, to store a password in encrypted form — run:

$ docker run -it --entrypoint node \
>   497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-platform-<bundle_name>:<tag> \
>   /opt/itential/platform/server/utils/encrypt.js <password_value> <encryption_key>

Replace <password_value> with the plaintext value to encrypt.

Common configuration tasks

Persist logs to the host

By default, container logs are lost when a container and its volumes are removed. To persist logs, mount a host directory into the container.

Create a log directory on the host

$ mkdir -p ./itential/platform/logs

Mount the directory when starting the container

The default log directory inside the container is /var/log/itential/platform. You can change this with the ITENTIAL_LOG_DIRECTORY environment variable.

$ docker run -d -p 3000:3000 -p 3443:3443 \
>   -e ITENTIAL_ENCRYPTION_KEY="<encryption_key>" \
>   --mount type=bind,source=./itential/platform/logs,target=/var/log/itential/platform \
>   497639811223.dkr.ecr.us-east-2.amazonaws.com/<bundle_name>:<tag>

Add SSH keys and certificates

Create a keys directory and place your files in it

$ mkdir -p ./itential/platform/keys

Set permissions on each key and certificate

Keys and certificates must be readable only by the file owner.

$ chmod 0400 custom_key.key
$ chmod 0400 custom_key.cert

Mount the directory and pass the file paths as environment variables

$ docker run -d -p 3000:3000 -p 3443:3443 \
>   --mount type=bind,source=./itential/platform/keys,target=/opt/itential/platform/keys \
>   -e ITENTIAL_ENCRYPTION_KEY="<encryption_key>" \
>   -e ITENTIAL_WEBSERVER_HTTPS_CERT="/opt/itential/platform/keys/custom_key.cert" \
>   -e ITENTIAL_WEBSERVER_HTTPS_KEY="/opt/itential/platform/keys/custom_key.key" \
>   497639811223.dkr.ecr.us-east-2.amazonaws.com/<bundle_name>:<tag>

Add adapters and custom applications

Create a directory and install the adapter

$ mkdir -p ./itential/platform/custom_adapters_apps/@itentialopensource
$ cd ./itential/platform/custom_adapters_apps/@itentialopensource
$ 
$ # Clone the adapter, then install its dependencies
$ cd open_source_adapter
$ npm install --install-strategy=nested --prod

Mount the directory and set the service directory environment variable

$ docker run -d -p 3000:3000 -p 3443:3443 \
>   -e ITENTIAL_ENCRYPTION_KEY="<encryption_key>" \
>   -e ITENTIAL_SERVICE_DIRECTORY="/opt/itential/platform/custom" \
>   --mount type=bind,source=./itential/platform/custom_adapters_apps/@itentialopensource,target=/opt/itential/platform/custom \
>   497639811223.dkr.ecr.us-east-2.amazonaws.com/<bundle_name>:<tag>

Run multiple containers for high availability

Multiple Platform containers can run together to provide high availability. Each container must:

Be bound to a unique host port
Connect to the same MongoDB and Redis instance

The following example starts two Platform containers sharing external MongoDB and Redis:

$ # Container 1
$ docker run -d \
>   -p 3000:3000 -p 3443:3443 \
>   -e ITENTIAL_ENCRYPTION_KEY="<encryption_key>" \
>   -e ITENTIAL_MONGO_URL="mongodb://host.docker.internal:27017" \
>   -e ITENTIAL_REDIS_HOST="host.docker.internal" \
>   --name IAP_instance1 \
>   497639811223.dkr.ecr.us-east-2.amazonaws.com/<bundle_name>:<tag>
$ 
$ # Container 2
$ docker run -d \
>   -p 3001:3000 -p 3444:3443 \
>   -e ITENTIAL_ENCRYPTION_KEY="<encryption_key>" \
>   -e ITENTIAL_MONGO_URL="mongodb://host.docker.internal:27017" \
>   -e ITENTIAL_REDIS_HOST="host.docker.internal" \
>   --name IAP_instance2 \
>   497639811223.dkr.ecr.us-east-2.amazonaws.com/<bundle_name>:<tag>