Install with Docker Compose¶

The Compose stack is the fastest path to a working Ampora and a faithful representation of the runtime — the Postgres-shaped backend, OIDC login, OpAMP WebSocket, OTel-exported self-observability — at the cost of running on a single host.

Use Compose for development, demos, integration tests, training environments, and small single-host pilots. Do not run production fleets on Compose: there is no HA, no rolling upgrade, no certificate rotation orchestration.

Prerequisites¶

• Docker 24+ with the compose v2 plugin
• 4 GiB of RAM free for the stack
• The following ports unused on the host:

On Linux without Docker Desktop add this entry to /etc/hosts:

127.0.0.1 host.docker.internal

Quickstart¶

From the repo root:

docker compose up --build

The first start builds the ampora/web:dev image, imports the ampora Keycloak realm, and runs the EF migrations against PostgreSQL. After about a minute open http://localhost:8080, log in as alice / password.

To shut everything down and drop volumes for a clean slate:

docker compose down -v

What is in the stack¶

Pre-seeded Keycloak users (password password):

Keycloak admin console: http://host.docker.internal:8081 (admin / admin).

Customising the stack¶

Use your own database¶

Stop the postgres service in compose and override the connection string:

services:
  ampora:
    environment:
      ConnectionStrings__Ampora: "Host=my-managed-pg.acme.io;Database=ampora;Username=ampora;Password=...;SSL Mode=Require"

Use your own OIDC provider¶

Replace the keycloak service block and override:

services:
  ampora:
    environment:
      Authentication__Oidc__Authority:    "https://login.acme.io/realms/ampora"
      Authentication__Oidc__ClientId:     "ampora-web"
      Authentication__Oidc__ClientSecret: "..."

Pin a specific image¶

If you do not want to build from source, swap the ampora build: block for a registry image:

services:
  ampora:
    image: registry.example.com/ampora/web:1.4.2

The published images are produced by the GitLab CI pipeline; see Operator → Operations → Upgrades for the versioning policy.

Logs and troubleshooting¶

docker compose logs -f ampora       # tail Ampora
docker compose logs -f postgres
docker compose logs -f keycloak

If the UI never lands on the Keycloak login page, the Authority URL almost always mismatches between the browser and the Ampora container; see Troubleshooting → OIDC.

Production warning¶

The Compose stack uses HTTP, dev-mode Keycloak, MinIO root credentials, and read_only: true containers without persistent volumes for some services. It is built for integration testing, not production. The production target is Kubernetes.