Get started with Elevarq Analyzer

What you'll build

Elevarq is a pipeline. This tutorial stands up the unified image — Analyzer, Insight, and Workbench in one container. Workbench is the surface you reach: it stores its own state in an embedded database and presents the findings the bundled Analyzer produces for you to triage. Neither the image nor Workbench connects to your PostgreSQL; the Signals collector does that, with a read-only role, and is set up separately.

Prerequisites

• Docker Engine 24+ with the Compose plugin (docker compose version prints a version).
• Outbound HTTPS to ghcr.io to pull the image. The unified image bakes the language model, so it is multiple GiB (size depends on the variant). After the pull, the deployment makes no outbound network calls by default — inference runs locally in Insight, and license activation and refresh are local artefact operations, not a phone-home.
• One TCP port reachable from operators — default 8080.
• Enough RAM for the variant floor (~6 GiB for small-cpu), plus several GiB of free disk for the image and the data, identity, and snapshot volumes.
• An activated license file (license.json) from Elevarq. Don't have one yet? Request an evaluation. You can complete steps 1–3 without it and activate later.

1. Generate the master key

Workbench refuses to boot without a master key — WORKBENCH_MASTER_KEY (or WORKBENCH_MASTER_KEY_FILE). It is the root of at-rest encryption: it protects every stored database password and integration credential. Generate one as a file and lock it down — this guide mounts it as a Docker secret rather than putting it in the environment:

mkdir -p secrets
openssl rand -hex 32 > secrets/workbench-master-key
chmod 600 secrets/workbench-master-key

2. Write the Compose file

Create docker-compose.yml. Deploy the variant your license entitles and pin a specific published release for <version>(take the latest from the release page — don't assume a latest tag exists). This example uses small-cpu. The master key is mounted as a Docker secret, and the deployment keeps three named volumes — Workbench data, the persistent identity, and the snapshot inbox where Signals exports land.

services:
  elevarq:
    image: ghcr.io/elevarq/elevarq:v<version>-small-cpu   # pin a digest in production (see below)
    container_name: elevarq
    restart: unless-stopped
    ports:
      # Only :8080 (Workbench) is published; Insight and the model
      # server stay on loopback inside the container. Bind to 127.0.0.1
      # and put a TLS proxy in front for anything beyond local (see note).
      - "127.0.0.1:8080:8080"
    environment:
      # REQUIRED. The unified image fails closed without the master key.
      WORKBENCH_MASTER_KEY_FILE: /run/secrets/workbench_master_key
      # Honour X-Forwarded-Proto from your TLS proxy so Workbench builds
      # https links (needed for the Secure session cookie). Leave unset
      # for a purely loopback first look.
      WORKBENCH_TRUST_FORWARDED_FOR: "true"
      # Optional — the container boots unlicensed (activation UI stays
      # reachable); a licensed run reads the artefact from here.
      ELEVARQ_LICENSE_PATH: /var/lib/arq/arq-license.json
    secrets:
      - workbench_master_key
    volumes:
      - elevarq-workbench:/var/lib/workbench
      - elevarq-identity:/var/lib/arq
      - elevarq-snapshots:/var/lib/elevarq/snapshots
    # Internal tokens are minted fresh each boot on this tmpfs.
    tmpfs:
      - /run/elevarq:mode=700,uid=1001
    security_opt:
      - no-new-privileges:true

secrets:
  workbench_master_key:
    file: ./secrets/workbench-master-key

volumes:
  elevarq-workbench:
    driver: local
  elevarq-identity:
    driver: local
  elevarq-snapshots:
    driver: local

3. Start it and confirm health

# 1. Start the service.
docker compose up -d

# 2. Wait for the container to become healthy.
docker compose ps

# 3. Confirm Workbench is responding.
curl -fsS http://127.0.0.1:8080/healthz

A healthy /healthz returns HTTP 200 with a JSON body of this shape:

{"status":"ok","version":"v<version>","schema_version":30,"uptime_seconds":12,"licensing":{"cache_state":"empty"}}

cache_state: "empty" is correct on a fresh install — it becomes fresh after you activate a license in step 5.

4. Create the first admin

On first run Workbench is unconfigured. The first thing you do is create the admin account. The bootstrap endpoint refuses a second call once an admin exists, so this is safe to expose during setup.

From the browser (recommended): open http://127.0.0.1:8080. A fresh install renders an admin-creation form — submit an email, display name, and a strong password, and you are logged in.

Or via the API (automation):

WORKBENCH=http://127.0.0.1:8080

# A fresh install returns {"bootstrap_required": true}
curl -fsS "$WORKBENCH/api/setup/status"

# Create the first admin (201 Created; a second call returns 409 Conflict).
curl -fsS -X POST "$WORKBENCH/api/setup/admin" \
  -H 'Content-Type: application/json' \
  -d '{
        "email": "you@example.com",
        "display_name": "First admin",
        "password": "<a-strong-password>"
      }'

# Log in; keep the session cookie jar for the next step.
curl -fsS -X POST "$WORKBENCH/api/auth/login" \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"<the-password-you-chose>"}' \
  -c /tmp/wb.cookies

5. Activate your license

License activation is operator-initiated: you upload the activated license.json Elevarq provided, and Workbench verifies its embedded signature against the public key ring. Using the cookie jar from step 4:

curl -fsS -X POST "$WORKBENCH/api/license" \
  -b /tmp/wb.cookies \
  -H 'Content-Type: application/json' \
  -H "X-Workbench-CSRF: $(grep workbench_csrf /tmp/wb.cookies | awk '{print $7}')" \
  --data-binary @license.json

A successful activation returns 200 OK with the parsed license summary (plan tier, valid-until, configured limits). The artefact is persisted to the data volume. Verify:

curl -fsS "$WORKBENCH/api/licenses" -b /tmp/wb.cookies
# {"plan": "...", "status": "LICENSE_VALID", ...}

# /healthz now reports the licensing cache as "fresh":
curl -fsS http://127.0.0.1:8080/healthz

Where next

You now have a healthy, licensed Workbench. The remaining steps connect it to your databases and your workflow:

• Connect your databases. Set up the Signals collector against each database (read-only role, TLS), then register each database's target metadata in Workbench so findings are hardware-aware.
• Run your first evaluation and review the findings in the Workbench UI. For what an evaluation looks like and how to read a finding, see the evaluation guide.
• Connect a ticket system (GitHub, GitLab, or Jira) so findings enter the same triage workflow as everything else — and add operators as local users or via SSO.

Each of these has a dedicated how-to guide in this manual's How-to guides section.