Configuration

All Admina settings are configured via admina.yaml or environment variables. A few settings accept both forms — the PII engine, for instance, is the top-level pii_engine: key in admina.yaml (a sibling of forensic_store: and auth_provider:, not nested under domains) or the ADMINA_PII_ENGINE environment variable — while others, such as the gateway variables and ADMINA_GUARD_FAIL_MODE, are environment-variable-only. Secrets are auto-generated on first launch and stored in an encrypted vault (.admina/secrets.json). The defaults are tuned so that the full Docker Compose stack lands in the OISG adequate band out of the box, and a bare pip install lands at 75, in the Good coverage band; turning any capability off immediately lowers the score. There are four supported bootstrap paths:

# 1. CLI (recommended) — local mode, no Docker
pip install admina-framework
admina init my-project
cd my-project && admina dev

# 2. Generate admina.yaml interactively (or non-interactively for CI)
admina configure                  # interactive wizard
admina configure --non-interactive # scaffolds defaults to ./admina.yaml

# 3. Docker Compose without the CLI
./scripts/bootstrap-secrets.sh   # writes random creds to .env
docker compose up --build

# 4. Manual
cp .env.example .env                # then fill in values

Authentication

Admina ships with dashboard authentication enabled by default. Two credentials drive the platform:

• ADMINA_API_KEY — protects every governance endpoint. The only exempt paths are /health, /docs, /openapi.json, /redoc, /metrics and the bundled dashboard shell (/, /heimdall.png, /vendor/*) — the dashboard's own /api/* calls still authenticate, via a signed session cookie. Note that /metrics serves Prometheus counters unauthenticated: keep it off the public internet or in front of your own reverse proxy.
• ADMINA_DASHBOARD_PASSWORD — shared login for the bundled Alpine.js dashboard, Grafana, and ClickHouse.

Both can be managed via the CLI:

admina password show      # display current credentials
admina password reset     # regenerate all credentials
admina password set       # set a custom password

Include the API key in every request to a protected endpoint:

# Via header
curl http://localhost:8080/api/stats \
  -H "X-API-Key: $ADMINA_API_KEY"

# Via Bearer token
curl http://localhost:8080/api/stats \
  -H "Authorization: Bearer $ADMINA_API_KEY"

For local development only, set ALLOW_UNAUTHENTICATED=true to disable auth. A warning is logged at startup. The docker-compose default is false.

All variables

These three are environment-variable-only — there is no admina.yaml equivalent. See API Reference → OpenAI-compatible gateway.

Leaving ADMINA_FORENSIC_STATE_KEY unset is not a vulnerability: the state file is simply unsigned, and the baseline truncation protection — reconstructing the chain state from the persisted records — is retained.

Programmatic form. Both classes take the key as the keyword argument state_signing_key: str | None = None. The explicit argument wins; the environment variable is only read when the argument is left at None (or empty), so SDK users need no env var at all:

from admina.domains.compliance.forensic import ForensicBlackBox
from admina.plugins.builtin.forensic.filesystem import FilesystemForensicStore

# key material comes from your own secret manager — never hardcode it
box = ForensicBlackBox(
    filesystem_dir="/var/lib/admina/forensic",
    state_signing_key=signing_key,
)
store = FilesystemForensicStore(
    base_dir="/var/lib/admina/forensic",
    state_signing_key=signing_key,
)

Choose your forensic backend deliberately. The hash chain that makes Admina's audit trail tamper-evident depends on persistent storage. The no-config fallback is memory (records lost on restart); since v0.9.5 the admina init templates and the dev docker-compose.yml scaffold with filesystem instead:

There is no environment variable that selects the active domains — each one is toggled individually in admina.yaml under domains.<name>.enabled (data_sovereignty, ai_infra, agent_security, compliance). Three of them ship enabled; ai_infra is opt-in and defaults to false.

Where does admina.yaml come from? There is no environment variable for its path, and no --config flag. The library loader looks for admina.yaml in the current working directory, then in the installed package root, and falls back to environment variables / .env when neither exists; the CLI is stricter — admina dev reads admina.yaml from the current directory only and exits if it is missing. To write one somewhere else, use admina configure -o /path/to/admina.yaml (the --output flag defaults to ./admina.yaml).

Docker Compose environment

When using the included docker-compose.yml, run ./scripts/bootstrap-secrets.sh to generate all secrets at once. The script writes random values to .env and is idempotent — rerun with --force to regenerate.

./scripts/bootstrap-secrets.sh
docker compose up --build

# An API key and one password shared by every UI — the two values the
# script prints. Both are written to .env:
ADMINA_API_KEY=<random 32-byte hex>
ADMINA_DASHBOARD_PASSWORD=<random 20-char password>
CLICKHOUSE_PASSWORD=<same value>
GRAFANA_ADMIN_PASSWORD=<same value>
MINIO_SECRET_KEY=<same value>      # unused residue of the removed MinIO backend (v0.9.5)

# .env also gets a separate, unprinted WEBUI_SECRET_KEY (another random
# 32-byte hex), used only by the Open WebUI service that `admina init`
# adds to its compose file when the ai_infra domain is on.

Production checklist

• Run bootstrap-secrets.sh (or let the CLI vault generate them) — never commit .env
• Leave ALLOW_UNAUTHENTICATED at its false default
• Use FORENSIC_BACKEND=s3 with TLS and Object Lock for a tamper-evident production audit trail
• Set ADMINA_FORENSIC_STATE_KEY so the forensic chain-state file is HMAC-signed — an unsigned or tampered state is then detected and the chain rebuilt from the records
• Decide your guard fail mode deliberately: ADMINA_GUARD_FAIL_MODE=closed makes a guard exception a BLOCK instead of a skipped check
• Configure CORS_ORIGINS to your actual frontend domains (the proxy warns on wildcard)
• Set LOG_LEVEL=WARNING to reduce log volume
• Point OTEL_ENDPOINT to your observability platform