Docker beta quickstart

This quickstart is the fastest way to try the SkeinRank platform beta instead of only the local SDK/CLI. It starts the governance console, API, PostgreSQL, Elasticsearch, RabbitMQ/Celery worker, and the services needed for the current profile → binding → enrichment → snapshot → search workflow.

Beta deployment path

This guide is for local evaluation and beta dogfooding. Do not expose the dev stack directly to the public internet. Production hardening, image publishing, upgrade notes, and reverse-proxy guidance are tracked separately.

What this starts

Governance UI

React console for Dashboard, Terms, Suggestions, Guardrails, Integrations, Snapshots, Search Playground, API Access, and Users.

Governance API

FastAPI backend for profiles, terms, bindings, jobs, runtime search, tokens, and users.

PostgreSQL

Stores profiles, terms, aliases, suggestions, bindings, users, tokens, and job metadata.

Elasticsearch

Document/search index used by evidence checks, dry-runs, enrichment, and runtime search preview.

RabbitMQ + worker

Runs async enrichment jobs and background processing used by the platform preview.

Optional observability

Prometheus, Grafana, and OpenTelemetry collector through the Compose observability profile.

Requirements

Docker Desktop or Docker Engine with Compose V2
Git
At least several GB of free RAM for PostgreSQL, Elasticsearch, RabbitMQ, API, worker, and UI
Node.js/Python are not required for the Docker path unless you also develop packages locally

Check Compose:

docker compose version

1. Clone the monorepo

git clone https://github.com/SkeinRank/skeinrank.git
cd skeinrank

2. Create local environment files

Start from the example files in the repository:

cp .env.example .env

For local beta testing, check these values in .env:

SKEINRANK_GOVERNANCE_API_AUTH_ENABLED=true
SKEINRANK_GOVERNANCE_API_BOOTSTRAP_ADMIN=true
SKEINRANK_GOVERNANCE_API_ADMIN_USERNAME=admin
SKEINRANK_GOVERNANCE_API_ADMIN_PASSWORD=change-me-local-only
VITE_SKEINRANK_GOVERNANCE_API_URL=http://127.0.0.1:8010

Shell environment has priority

If a variable is already exported in your terminal, Docker Compose can use that value instead of the value from .env. If auth behaves unexpectedly, run env | grep SKEINRANK_GOVERNANCE_API_AUTH and unset stale variables.

Useful check:

env | grep SKEINRANK_GOVERNANCE_API_AUTH

If you see an old value that should not apply:

unset SKEINRANK_GOVERNANCE_API_AUTH_ENABLED

3. Start the beta stack

Use the dev Compose file from the monorepo root:

docker compose -f docker-compose.dev.yml up --build -d

If you also want Prometheus, Grafana, and the OpenTelemetry collector:

docker compose -f docker-compose.dev.yml --profile observability up --build -d

4. Check service status

docker compose -f docker-compose.dev.yml ps

With the observability profile:

docker compose -f docker-compose.dev.yml --profile observability ps

Expected local entry points:

Service	URL
Governance console	`http://127.0.0.1:5173`
Governance API	`http://127.0.0.1:8010`
API health	`http://127.0.0.1:8010/healthz`
API readiness	`http://127.0.0.1:8010/readyz`
Prometheus, optional	`http://127.0.0.1:9090`
Grafana, optional	`http://127.0.0.1:3000`

Check auth is enabled:

curl -i http://127.0.0.1:8010/v1/auth/me

A protected dev stack should return:

HTTP/1.1 401 Unauthorized
{"detail":"Missing bearer token"}

Open the console:

http://127.0.0.1:5173

Then follow this path:

1. DashboardCheck setup readiness and the next action.

2. TermsCreate or import a terminology profile with canonical terms and aliases.

3. IntegrationsCreate an Elasticsearch binding and run a dry-run.

4. EnrichmentRun a default enrichment job from the jobs panel.

5. Search PlaygroundTest a query such as k8s pg timeout.

A binding is the key runtime unit:

profile + index/alias + text fields + target field + optional discriminator + runtime snapshot

For shared indexes, create multiple bindings:

binding #1: profile infra   → index company_docs → team=infra
binding #2: profile legal   → index company_docs → team=legal
binding #3: profile support → index company_docs → team=support

6. Stop the stack

Stop containers but keep dev volumes:

docker compose -f docker-compose.dev.yml down

With observability profile:

docker compose -f docker-compose.dev.yml --profile observability down

Reset all dev data, including PostgreSQL, Elasticsearch, and RabbitMQ volumes:

docker compose -f docker-compose.dev.yml --profile observability down -v --remove-orphans

Data reset warning

down -v deletes local dev data. Use it only when you intentionally want a clean PostgreSQL/Elasticsearch/RabbitMQ state.

Troubleshooting

Compose says no configuration file was found

Run Compose from the monorepo root and pass the dev file explicitly:

docker compose -f docker-compose.dev.yml down

The file name itself is not a command:

# Wrong
docker-compose.dev.yml down

Auth looks disabled even though `.env` says true

Check for exported variables in your shell:

env | grep SKEINRANK_GOVERNANCE_API_AUTH

Remove stale values and recreate the API/UI containers:

unset SKEINRANK_GOVERNANCE_API_AUTH_ENABLED
docker compose -f docker-compose.dev.yml --profile observability up -d --force-recreate governance-api governance-worker ui

A migration container exited

Inspect logs:

docker compose -f docker-compose.dev.yml logs --tail=200 governance-migrate

For the observability profile:

docker compose -f docker-compose.dev.yml --profile observability logs --tail=200 governance-migrate

What this guide does not cover yet

Production reverse proxy and TLS setup
Published GHCR/Docker Hub image tags
Upgrade compatibility policy
Backup/restore procedure
Security hardening checklist
Public SaaS or multi-tenant deployment

Those topics belong to the deployment and production-readiness docs rather than the local Docker beta quickstart.