Skip to content

Docker Compose Deployment

Audience: Administrators deploying Sentari on a single server or VM

What you need: the Docker Compose bundle (download from your Sentari release), Docker Engine 24+, a Sentari license key, and network (or mirror) access to the container images. No source repository required.

This bundle deploys the full Sentari server stack — API, versioned API-docs site, background workers, TimescaleDB, and Redis — from published container images, in one command.

Contents of this bundle

File Purpose
docker-compose.yml The stack definition (image-only — no build step).
.env.example Template for your secrets and settings.
README.md This guide.

Prerequisites

  • A Linux server (amd64), 4 GB RAM minimum (8 GB recommended), 40 GB+ disk.
  • Docker Engine 24+ with the Compose plugin (docker compose version).
  • Ports 8000 (API + dashboard) and 8001 (API docs) reachable by your users.
  • A Sentari license key and image pull access (public ghcr.io, or your internal mirror — see Air-gap / private registry).

Step 1 — Prepare the environment file

From inside the bundle directory:

cp .env.example .env
chmod 600 .env
$EDITOR .env

Fill in every REPLACE-WITH-... value. Generate the cryptographic ones:

# SENTARI_SECRET_KEY (64 hex chars)
python3 -c "import secrets; print(secrets.token_hex(32))"

# SENTARI_CONFIG_KEY (base64, 32 bytes)
python3 -c "import os,base64; print(base64.b64encode(os.urandom(32)).decode())"

# SENTARI_ENROLLMENT_TOKEN / passwords
python3 -c "import secrets; print(secrets.token_hex(16))"

Pin the release for production — set VERSION= to a specific tag instead of latest.

Step 2 — Provision the license-map signing key

The server signs the install-gate policy map that agents fetch. It never auto-generates this key — create it once into the ca-data volume before starting the stack:

# Create the named volume and write the key into it
docker volume create docker-compose_ca-data >/dev/null 2>&1 || true
docker run --rm -v docker-compose_ca-data:/ca alpine/openssl \
  genpkey -algorithm ed25519 -out /ca/license_map_signing.key
docker run --rm -v docker-compose_ca-data:/ca alpine \
  chmod 600 /ca/license_map_signing.key

The volume name is <folder>_ca-data. If you renamed the bundle directory, adjust accordingly (docker volume ls to confirm).

Step 3 — Start the stack

docker compose up -d

Compose pulls the images and starts all services. First start runs database migrations and creates the bootstrap admin account.

Step 4 — Verify the deployment

# All services should be "healthy"
docker compose ps

# API health
curl -sf http://localhost:8000/api/health
# Expected: {"status": "ok", "version": "..."}

Then open the dashboard at http://:8000 and log in with the SENTARI_BOOTSTRAP_ADMIN_EMAIL / SENTARI_BOOTSTRAP_ADMIN_PASSWORD you set. Change the admin password after first login.

The API documentation is at http://:8001.

Step 5 — Enroll your first agent

Install the agent on an endpoint and point it at this server with the enrollment token from your .env. See the Agent deployment guide.

Within a few minutes the device appears under Devices in the dashboard and its package inventory + CVE correlation populate.

Optional: SSO and LDAP

Uncomment and set the SENTARI_OIDC_* / SENTARI_LDAP_* values in .env, then docker compose up -d to apply. OIDC supports Keycloak, Azure Entra ID, Ping, Okta; LDAP requires ldaps:// in production. See the Configuration Reference for the full list.

TLS / production hardening

This bundle serves plain HTTP on 8000/8001. For production, put a TLS-terminating reverse proxy (nginx, Caddy, your load balancer) in front, and:

  • Terminate HTTPS and forward to 127.0.0.1:8000.
  • Set SENTARI_ALLOWED_ORIGINS to your HTTPS dashboard URL.
  • Keep SENTARI_MTLS_REQUIRED=true; the terminator forwards the agent client certificate fingerprint as X-Client-Cert-Fingerprint.

Air-gap / private registry

Mirror these images into your internal registry, then set REGISTRY= in .env to its prefix:

  • ghcr.io/sentari-dev/sentari/server:<version>
  • ghcr.io/sentari-dev/sentari/docs:<version>
  • docker.io/timescale/timescaledb:2.14.2-pg16
  • docker.io/redis:7.2-alpine

For air-gap licensing, your license key carries a signed max_offline_days claim — the server runs without phoning home for that window.

Managing the stack

docker compose logs -f sentari-api    # tail API logs
docker compose down                    # stop (data preserved in volumes)
docker compose pull && docker compose up -d   # upgrade to a new VERSION
docker compose down -v                 # stop AND delete all data (irreversible)

Troubleshooting

API container restarts / won't start. Check docker compose logs sentari-api. Most common causes: SENTARI_SECRET_KEY still the placeholder; SENTARI_MTLS_REQUIRED=false without SENTARI_DEBUG=true; wrong POSTGRES_PASSWORD on an existing db-data volume (recreate with docker compose down -v if this is a fresh install).

Agent can't connect. Verify curl http://<server>:8000/api/health from the endpoint and that the enrollment token matches.

No scans in the dashboard. Confirm the agent service is running on the endpoint and check its log for upload errors.

For assistance, contact your Sentari representative.