Install Guide

Installation by deployment type

Identified candidate: Docker Compose

Use the supplied candidate bundle and its CANDIDATE.json manifest. Local candidate images must already be loaded on this machine. Compose runs separate API, authorisation, worker and database services; it does not use the old all-in-one preview topology.

Requirements: Docker Compose v2, openssl, Python 3.11+, and the candidate bundle with its SDK wheel. Choose unused loopback ports and a new project name. Do not reuse a customer or development database.

1. 1

   Open the supplied candidate bundle

   cd /path/to/candidate/bundle
   set -a
   . ../images.env
   set +a

2. 2

   Generate configuration

   The generator writes all required secrets to a private .env file and refuses to overwrite one. Current candidates use database-resolved identity credentials; do not add the old TOKEN_SECRET setting.

   bash gen-env.sh
   mkdir -m 700 out
   export CLAIIM_UID=$(id -u)
   export CLAIIM_API_PORT=127.0.0.1:18181 CLAIIM_UI_PORT=127.0.0.1:13001
   export COMPOSE_PROJECT_NAME=claiim-candidate-YOUR_UNIQUE_RUN_ID
   docker compose --env-file .env --profile ui config --quiet

3. 3

   Start CLAIIM

   docker compose --env-file .env --profile ui up --pull never -d --wait
   docker compose --env-file .env run --rm --no-deps tenant \
     -name Evaluation -admins admin@claiim.io,peer@claiim.io \
     -password-file /out/admin.pw

   The one-shot migration and role jobs prepare the database. Tenant provisioning creates its root organisation and two administrators; the generated password is written to out/admin.pw. There are no built-in demo credentials in this candidate.

4. 4

   Verify the API is healthy

   curl --fail http://127.0.0.1:18181/readyz
   # Expected: {"status":"ready"}

5. 5

   Open the admin panel

   Navigate to http://127.0.0.1:13001/login and log in asadmin@claiim.io with the generated password in out/admin.pw.

6. 6

   Run the gate proof

   Follow the Onboarding guide using the provisioned tenant root. Its manual SDK example runs two gate calls, one ALLOW and one DENY, for review in Chron.

   python3 -m venv .venv
   . .venv/bin/activate
   python -m pip install --no-index ./sdk/claiim_sdk-0.1.0-py3-none-any.whl
   python -c "from claiim import CLAIIMClient; print('SDK import OK')"

   Continue with Onboarding, including the manual gate test and both Chron records. No downstream deployment is performed.

Stop CLAIIM

docker compose --env-file .env --profile ui down  # stop, keep this project's data
# Only for your disposable evaluation project, after saving evidence:
docker compose --env-file .env --profile ui down --volumes --remove-orphans

Database profiles and legacy configuration

The configuration below is for the older published all-in-one preview only, not the current candidate or a production installation. Its onboarding acceptance has failed; it must not substitute for the candidate workflow above. A current-source external database needs separate restricted roles and connection settings for every workload.

For the published evaluation preview images, provision a dedicated PostgreSQL 16+ database and a login able to run the preview schema migrations. The database hostname must be reachable from the API container; localhost inside that container is not your database server. Configure database TLS and percent-encode special characters in the connection URL. This setup does not establish production readiness and is not the separate-workload topology used by current source builds.

Use a standalone file named compose.external-db.yml with the complete configuration below. Do not merge it with the bundled compose.yml:

services:
  claiim-api:
    image: ghcr.io/nivaya/claiim-api:preview
    environment:
      DATABASE_URL: ${DATABASE_URL:?set DATABASE_URL in .env}
      TOKEN_SECRET: ${TOKEN_SECRET:?set TOKEN_SECRET in .env}
      TIER: ${TIER:-community}
      PORT: "8181"
      LOG_LEVEL: ${LOG_LEVEL:-info}
      CHRON_QUEUE_WORKERS: "4"
    ports:
      - "127.0.0.1:8181:8181"
    restart: unless-stopped

  claiim-ui:
    image: ghcr.io/nivaya/claiim-ui:preview
    environment:
      PORT: "3001"
    ports:
      - "127.0.0.1:3001:3001"
    depends_on:
      - claiim-api
    restart: unless-stopped

Set both values in .env (use your own database URL and a generated secret, not these placeholders). Keep this file private and out of version control:

DATABASE_URL=postgres://your_user:your_encoded_password@your_db_host:5432/claiim?sslmode=verify-full
TOKEN_SECRET=replace_with_output_of_openssl_rand_hex_32

chmod 600 .env
docker compose --env-file .env -f compose.external-db.yml config --quiet
docker compose --env-file .env -f compose.external-db.yml up -d
docker compose --env-file .env -f compose.external-db.yml logs claiim-api
curl --fail http://localhost:8181/health

# Stop this configuration (the external database is not removed):
docker compose --env-file .env -f compose.external-db.yml down

The preview API runs migrations on startup; check its logs and health response before onboarding. The Compose configuration check validates interpolation and dependencies, not database reachability, TLS, migration permissions, or image acceptance. Back up the database before migrating and configure retention and restore procedures separately. Registry access is still required. UI and API ports above are bound to loopback only.

Older all-in-one configuration

These variables describe the older preview only. For the candidate, retain the complete generated .env and Compose workload configuration; TOKEN_SECRET is not a candidate setting.

Production paths are in development

The Professional track targets customer-managed PostgreSQL with Kubernetes or VM deployment. Operational acceptance and enterprise hardening are pending.

The Sovereign track targets offline delivery of images, deployment configuration, migrations, and licensing. Verified air-gap installation and updates remain in development.