Installation

One installer stands up the entire stack — gateway, dashboard, PostgreSQL, nginx edge, and Keycloak SSO — on a single Docker host. Editions are compose overlays on the same image, so growing from Lite to Pro to Distributed is a configuration change, not a migration.

Check the system requirements first, and have your image reference and public URL ready.

Standalone (single host)

From the unpacked install bundle:

cd deploy
./install.sh --url https://aam.example.com --variant lite    # Lite  (no OpenSearch, no SOAR)
./install.sh --url https://aam.example.com --variant base    # Base  (+ SOAR containment)
./install.sh --url https://aam.example.com                   # Pro   (default — SIEM on OpenSearch)
./install.sh --url https://aam.example.com --variant proai   # Pro AI (+ guardrail AI sidecars)

The installer:

1. generates every secret into deploy/.env (database passwords, the catalog master key, SSO client secrets),
2. renders the Keycloak realm for your URL,
3. pulls the image and starts the stack, and
4. prints the dashboard URL and a one-time admin password (SSO forces a password change on first sign-in).

Re-running it is safe and is also the upgrade path: existing secrets are kept, and the master key is never regenerated.

You can omit --url: the installer prompts, defaulting to http://<hostname>:8080, which is fine for a single box or LAN evaluation over plain HTTP. Use an https:// URL only when a TLS proxy fronts the appliance (see HTTPS below).

Windows: use .\install.ps1 with the same options (-Url, -Variant, -Image). If script execution is blocked: powershell -ExecutionPolicy Bypass -File .\install.ps1 ….

Distributed (scale-out)

The data plane is stateless — per-request virtual-key auth on /v1, dashboard sessions in Valkey — so the app scales horizontally once it points at shared PostgreSQL, Valkey, and OpenSearch. Two supported shapes:

Single host, N replicas (Docker Compose). compose/distributed.yml runs N app replicas behind nginx with bundled PostgreSQL, Valkey, and OpenSearch, with all the shared-state wiring set for you:

cd deploy
docker compose --env-file .env -f compose/distributed.yml up -d --build --scale app=3

Many machines (Kubernetes). Use the Helm chart at deploy/helm/aimanager: N app replicas (Deployment + HPA + Ingress) pointing at your managed or external PostgreSQL, an OpenSearch cluster, and HA Valkey. This is the path for a real multi-machine, autoscaling deployment; the chart README in the bundle documents the values.

For what moves where when you scale out — and how to grow an existing single box into a cluster without losing data — see Scale from one box to a cluster.

Bring your own identity provider

Use your existing Keycloak, Microsoft Entra ID, Okta, Google, or any OIDC provider instead of the bundled Keycloak:

1. Register a confidential OIDC client (authorization-code flow) with redirect URI https://<your-host>/login/oauth2/code/aim-dashboard, an audience/claim of aim-admin-api, and your admin group mapped to a realm role admin.
2. In deploy/.env set AIM_OIDC_ISSUER_URI, AIM_OIDC_CLIENT_ID, and AIM_OIDC_CLIENT_SECRET.
3. Install with the custom IdP flag, which omits the bundled Keycloak: ./install.sh --url https://<host> --idp custom.

Alternatively, keep the bundled Keycloak and federate your IdP inside it (Identity Providers, or User Federation for LDAP/AD) at https://<host>/auth/admin — no app configuration change. Full details in Keycloak & OIDC providers.

HTTPS (on-prem)

The bundled stack serves plain HTTP on the published port; the app honours X-Forwarded-Proto, so TLS is a deployment choice, not an app requirement. Two ways to get HTTPS:

1. Front it with your TLS-terminating proxy, load balancer, or ingress (recommended). It holds the certificate and forwards to http://<appliance-host>:8080 with X-Forwarded-Proto: https. Set AIM_PUBLIC_URL=https://aam.example.com so secure cookies and the OIDC issuer are https. The appliance itself needs no certificate.
2. Terminate TLS in the bundled nginx: add a listen 443 ssl server block to deploy/compose/nginx.conf, mount your certificate and key into the nginx container, and publish 443. A certificate from your internal CA is the norm on-prem.

Day-2 operations

Always use the same -f compose files you installed with — the installer prints them (compose/standalone.yml for Lite/Base, plus compose/standalone.pro.yml for Pro, plus compose/standalone.ai.yml for Pro AI).

Full decommission also removes deploy/.env — but that destroys the catalog master key, so keep it if you might ever reinstall against the same data.

After installing