A local development environment for Itential Platform and related technologies.

Note: This environment is for development and testing only. Do not use in production.

• Docker (v20.10+) with Docker Compose (v2.0+)
• Access to an image registry — either AWS ECR or JFrog (see Image Registries)

cp .env.example .env    # make setup also does this if .env doesn't exist

Open .env and configure:

Choose what to run — pick a base profile and enable the services you need:

# Base profile: full | platform | deps
#   full     = MongoDB, Redis, Platform, Gateway4, Gateway5
#   platform = MongoDB, Redis, Platform (most common)
#   deps     = MongoDB, Redis only
STACK_PROFILE=platform

# Enable individual services on top of the base profile
GATEWAY5_ENABLED=true
LDAP_ENABLED=true
# MCP_ENABLED=true
# OPENBAO_ENABLED=true

Choose your image registry — uncomment one set:

# AWS ECR (default — requires: make login)
PLATFORM_IMAGE=497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-platform-config-lcm:6
GATEWAY5_IMAGE=497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-gateway5:5.1.0-amd64

# JFrog (requires: docker login itential.jfrog.io)
PLATFORM_IMAGE=itential.jfrog.io/flowai/itential_flowai:v0.0.6
GATEWAY5_IMAGE=itential.jfrog.io/flowai/itential_flowai_gateway5:5.3.0-amd64

make setup

This generates an encryption key, creates SSL certificates, starts your services, and configures Gateway Manager and any enabled optional services.

make up       # Start services
make down     # Stop services
make logs     # View logs (or: make logs LOG=platform)
make status   # Check status and URLs

The profile system has two layers that let you run exactly what you need:

Base profile (STACK_PROFILE) determines the core services:

Enable flags add individual services on top of the base profile:

# Platform + Gateway5 + LDAP (no Gateway4)
STACK_PROFILE=platform
GATEWAY5_ENABLED=true
LDAP_ENABLED=true

# Full stack (everything)
STACK_PROFILE=full

# Platform only (minimal)
STACK_PROFILE=platform

Both make setup and make up respect these settings automatically.

You can also use docker compose directly with profiles:

docker compose --profile platform up -d
docker compose --profile platform --profile ldap up -d
docker compose --profile full --profile openbao up -d

All ports are configurable via .env — see Port Configuration.

All configuration is managed via .env (see Getting Started).

The configuration loads in two layers:

1. defaults.env — Version-controlled defaults (ECR images, dependency versions). Do not edit.
2. .env — Your overrides (git-ignored). Any variable set here takes precedence.

Always use make commands (make up, make down, etc.) to ensure both files are loaded correctly.

Image defaults are in defaults.env (version-controlled) and point to AWS ECR. Override in your .env:

AWS ECR (default):

# Requires: make login (or AWS CLI configured with ECR access)
PLATFORM_IMAGE=497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-platform-config-lcm:6
GATEWAY4_IMAGE=497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-gateway:4.3.7
GATEWAY5_IMAGE=497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-gateway5:5.1.0-amd64

JFrog:

# Requires: docker login itential.jfrog.io
PLATFORM_IMAGE=itential.jfrog.io/flowai/itential_flowai:v0.0.6
GATEWAY5_IMAGE=itential.jfrog.io/flowai/itential_flowai_gateway5:5.3.0-amd64

When using non-ECR images, make setup automatically skips AWS authentication.

Override in .env if defaults conflict with existing services on your machine:

Different platform images may run as different UIDs. The init container sets log directory ownership based on these variables:

The standard ECR image uses UID 1001. JFrog flowai images use UID 1000. To check an image: docker inspect <image> --format '{{.Config.User}}'

OpenLDAP provides enterprise LDAP authentication testing.

Enable: Set LDAP_ENABLED=true in .env, then make setup.

After setup, log in with any pre-configured user:

The MCP server enables LLM tools (Claude Code, Claude Desktop) to interact with Itential Platform.

Enable: Set MCP_ENABLED=true in .env, then make setup or make up.

See docs/itential-mcp for Claude Desktop configuration examples.

OpenBao provides Vault-compatible secrets management.

Enable: Set OPENBAO_ENABLED=true in .env, then make setup.

Setup automatically initializes OpenBao, saves the root token, enables KV v2, configures Platform integration, and installs the Vault adapter.

# Get your root token after setup
cat volumes/openbao/init-keys.json | jq -r '.root_token'

# Access the UI
open http://localhost:8200

export VAULT_TOKEN=$(cat volumes/openbao/init-keys.json | jq -r '.root_token')

# Write a secret
curl -X POST http://localhost:8200/v1/secret/data/myapp/config \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  -d '{"data": {"username": "admin", "password": "secret"}}'

# Read a secret
curl http://localhost:8200/v1/secret/data/myapp/config \
  -H "X-Vault-Token: $VAULT_TOKEN"

For detailed usage, see docs/openbao.

Gateway5 connects to Platform via Gateway Manager. make setup handles everything automatically:

1. Generates client certificates (volumes/gateway5/certificates/)
2. Uploads certificates to Platform via API
3. Configures RBAC (assigns gateway roles to admin)
4. Creates and enables the gateway cluster

If automatic configuration fails, the script displays manual instructions. See Gateway Manager docs.

To work on or demo IAG5 without the full Platform stack, deploy it on its own:

make iag5            # IAG5 only
make iag5-openbao    # IAG5 + OpenBao (side by side, initialized and unsealed)

Both targets generate certificates first and bring up IAG5 without a Platform. They require only the IAG5 image (no encryption key or .env); if the image is missing, the target attempts a pull and points you to make login for AWS ECR access.

With no Platform running, IAG5 logs recurring Gateway Manager connection retries against the default platform:8080 host. This is expected and harmless: the container stays up and the gRPC server listens on 50051. To point IAG5 at a real Platform (local or cloud) instead, set GATEWAY5_CONNECT_HOSTS in your .env.

make iag5-openbao brings up OpenBao alongside IAG5 and initializes it, but does not wire IAG5 to consume OpenBao secrets — the two simply run together. Get the OpenBao root token from volumes/openbao/init-keys.json.

Tear down with make down, which stops IAG5 and OpenBao together.

Note: An empty GATEWAY5_CONNECT_HOSTS is invalid for IAG5 and causes a startup panic, so the compose default always resolves to a non-empty host (platform:8080). Override it via .env to target a different Gateway Manager.

cd volumes/platform/adapters/
git clone https://gitlab.com/itentialopensource/adapters/adapter-servicenow.git
cd adapter-servicenow && npm install
cd ../../..
make up  # Restart to load adapter

Find adapters at Itential Automation Marketplace.

# Shell access
docker exec -it platform /bin/sh
docker exec -it gateway4 /bin/sh
docker exec -it gateway5 sh

# Database access
docker exec -it mongodb mongosh
docker exec -it redis redis-cli

# Check platform environment
docker exec platform env | grep ITENTIAL

This project is OCI-compliant and works with Podman. The simplest approach is to install Docker CLI emulation:

# Fedora/RHEL/CentOS
sudo dnf install podman-docker

# Ubuntu/Debian
sudo apt install podman-docker

With this installed, all make commands work unchanged.

podman-compose --profile platform up -d
podman-compose --profile platform down
podman-compose logs -f

# ECR auth
aws ecr get-login-password --region us-east-2 | \
  podman login --username AWS --password-stdin 497639811223.dkr.ecr.us-east-2.amazonaws.com

itential-dev-stack/
├── docker-compose.yml      # Service definitions
├── .env                    # Your configuration (git-ignored)
├── .env.example            # Configuration template
├── defaults.env            # Default values (version-controlled)
├── Makefile                # Make commands
├── scripts/
│   ├── setup.sh                     # First-time setup orchestrator
│   ├── generate-certificates.sh     # SSL cert generation
│   ├── configure-gateway-manager.sh # Gateway Manager config
│   ├── configure-ldap.sh           # LDAP adapter config
│   ├── configure-openbao.sh        # OpenBao init/unseal
│   └── sync-admin-roles.sh         # Admin role sync
├── docs/                   # Additional documentation
├── volumes/
│   ├── platform/           # Adapters, SSL certs, vault token
│   ├── gateway4/           # Playbooks, scripts, data
│   ├── gateway5/           # Certificates, scripts
│   ├── ldap/               # LDAP bootstrap config
│   ├── mcp/                # MCP logs
│   └── openbao/            # OpenBao config
└── dependencies/
    └── mongodb-data/       # MongoDB persistent data

• Platform Environment Variables
• Gateway4 Configuration
• Gateway5 Configuration
• Adapter Documentation