Installation Guide¶

This guide explains how to install the Identity Operations Platform using Docker Compose.
It is intended for customers and system integrators who want a reproducible and safe installation process.

The installation is driven by a control script that generates all required secrets as files and prepares the environment. After starting the containers, the installation routine must be run to complete the initial setup.

For consolidated host sizing, Docker runtime prerequisites, and infrastructure requirements, see System Requirements.

Before You Start¶

Before starting installation, validate host sizing and runtime prerequisites.

Reverse Proxy and `TRUSTED_PROXIES`¶

If the platform is operated behind a customer-managed reverse proxy or load balancer, TRUSTED_PROXIES must be adjusted to match the actual proxy source addresses in your network.

Set TRUSTED_PROXIES to the IPs/CIDRs of the proxy tier that forwards traffic to Identity Operations Platform.
Do not use overly broad values unless explicitly required by your network design.
If multiple proxy hops are used, include all trusted forwarding hops that may set X-Forwarded-* headers.

Example (.env):

TRUSTED_PROXIES=10.20.30.0/24,10.20.40.15/32

Incorrect TRUSTED_PROXIES values can cause wrong client IP detection, incorrect URL/scheme handling, and security issues around forwarded headers.

Recommended Production Sizing (Small to Medium Environments)¶

Plan at least 4 GB RAM per container for web, worker, leadworker, and database (PostgreSQL).
For each additional worker container, plan an additional ~4 GB RAM.
compose.yaml is tuned as a production-oriented baseline for small to medium deployments.
The platform has been tested with lower resource limits, but those lower limits are not the recommended production baseline.

Runtime Prerequisites¶

Docker is installed and running
Docker Compose is available
A working shell environment is available
The installation directory is writable

Prerequisites¶

Before starting the installation, ensure the following requirements are met:

Docker is installed and running
Docker Compose is available
A working shell environment is available
The installation directory is writable

No database or messaging services need to be installed manually.

Before installing the platform, log in to the AuthWire registry:

docker login registry.authwire.com

Credentials are provided together with the license key via email.

Optional: Signature Verification¶

All our Docker images are signed with Cosign. The public key is available at https://github.com/authwire/keyring.

Note

Signature verification is not handled by Docker Compose. Run Cosign verification before pulling or starting the stack.

Example verification:

cosign verify \
  --key cosign.pub \
  registry.authwire.com/authwire/iop@sha256:IMAGE_DIGEST

To fetch the digest for a tag, run:

docker manifest inspect registry.authwire.com/authwire/iop:TAG --verbose | jq -r '.Descriptor.digest'

Installation Overview¶

The installation process consists of four main steps:

Log in to the registry
Generate the environment configuration
Verify the generated configuration
Start the platform services

All sensitive secrets are generated automatically during installation. Follow the security instructions below very carefully.

Environment File Generation¶

The platform uses an environment file named .env for non-secret configuration values. All secrets are stored as files in the ./secrets directory.

Generating the Environment File¶

Run the following command:

./control.sh install iop.example.com

Replace iop.example.com with the publicly reachable fully qualified domain name under which the platform will be accessed.

Note

This must be the public, externally reachable address, otherwise token validation for platform access (for example Microsoft Graph) will fail.

This command performs the following actions:

generates cryptographically secure secrets as files in ./secrets
creates the .env file if it does not already exist
sets the server name and issuer values (SERVER_NAME, ECHOHUB_JWT_ISSUER, PLATFORM_TOKEN_ISSUER_URL)
prepares the deployment for first startup

If a .env file already exists, it will not be overwritten.

Generated Configuration Values¶

The environment file contains, among others:

server name and issuer configuration
HTTP/HTTPS ports

Secrets are stored as files in ./secrets and are mounted into containers as Docker secrets.

Generated Secret Files¶

compose.yaml is the source of truth for required secret files. The control script creates the following files in ./secrets to match it:

app_secret.sec
echohub_jwt_secret.sec
redis_password.sec
rabbitmq_password.sec
rabbitmq_definitions.json
database_password.sec
cache_keypair.hex
database_encryption_key.hex
database_integrity_key.hex
webserver_key.pem
webserver_certificate.pem
webserver_dhparam.pem
audit_private.pem
audit_public.pem

All values are generated with sufficient entropy and are suitable for production use.

Security Notes¶

the ./secrets directory contains sensitive secrets
file permissions are restricted during creation
secrets must not be committed to version control
store the ./secrets directory securely and back it up

Warning

Losing the ./secrets directory may result in permanent data loss if encryption keys cannot be recovered. Back up the secret files securely, and avoid storing them alongside database backups whenever possible. The secret files contain critical keys, and losing them will inevitably cause data loss. Back up the audit private key separately so audit log signatures can always be verified after a restore.

Verifying the Installation¶

After generating the environment file, verify that it exists:

ls -l .env

Verify that secrets were created:

ls -l secrets

Once the environment file is in place, start the platform services:

./control.sh start
./control.sh status

Initial Setup¶

The default configuration sets ENABLE_SETUP=true. This enables the installation routine that must run once to initialize the database and configure the primary authentication endpoint.

After starting the stack, open the setup routine at:

https://iop.example.com/setup

Replace iop.example.com with your actual server name.

After the setup is complete, remove ENABLE_SETUP from the .env file and restart the containers:

docker compose up -d

Updating the Environment¶

If configuration values need to be changed later:

edit the .env file manually
or regenerate a new file in a fresh installation directory

If you change the secrets directory location, update the Docker Compose secret file paths accordingly.

Changing secrets in an existing installation may break access to encrypted data.

Common Installation Mistakes¶

Avoid the following:

deleting the ./secrets directory after installation
regenerating secrets on an existing production system
committing the secret files to a repository
starting the platform without generating the environment file and secrets

Summary¶

The installation process is designed to be:

simple and automated
secure by default
reproducible across environments

Once the environment file is generated and the services are started, the platform is ready for further configuration and operation.