First run with Registry Lab

Registry Lab is the compose-based local demo for the registry stack. It wires Registry Platform source crates, three Registry Relay instances, four Registry Notary instances, live Postgres and Zitadel services, a private OpenFn sidecar path, a static metadata publisher, and narrated demo clients into a single topology you can run on a laptop.

Prerequisites

Docker with Compose v2.20 or later (required for additional_contexts support in the Dockerfiles).
uv CLI installed (used to run scripts/generate-fixtures.py, which is a PEP 723 inline-dependency script).
python3 and openssl on your PATH (used by scripts/generate-demo-secrets.py and scripts/demo-flow.py).
GitHub SSH access for submodules, or equivalent local Git configuration for the vendor/* submodule URLs.
No production secrets in the demo environment. The generated .env uses inert local credentials only.
A sibling ../registry-notary checkout when running the OpenFn sidecar path before the vendor/registry-notary submodule includes crates/registry-notary-openfn-sidecar.

Steps

Run the following commands in order from the registry-lab checkout root.

Step 1 uses uv run because generate-fixtures.py declares inline PEP 723 dependencies. Step 2 is a stdlib-only Python script; later steps are plain shell or Docker commands.

Generate synthetic fixture data for civil, social protection, and health registries:
Terminal window
```
uv run scripts/generate-fixtures.py
```
Generate the local demo .env with credential hashes and JWK issuer keys:
Terminal window
```
scripts/generate-demo-secrets.py
```
Publish the static metadata bundle (requires Step 1 to have completed, so the fixture data is present):
Terminal window
```
scripts/publish-static-metadata.sh
```
Build the compose images:
Terminal window
```
docker compose -f compose.yaml build
```
Steps 4-5 (image build) can take several minutes on first run. Don’t abort if it appears to pause.
Start all background services:
Terminal window
```
docker compose -f compose.yaml up -d
```
Run the smoke tests:
Terminal window
```
scripts/smoke.sh
```

Run the narrated demo client flow:

docker compose -f compose.yaml --profile client run --rm demo-client

Inspect the service-first graph in Registry Atlas:
Terminal window
```
cd ../registry-atlas
pnpm dev
```
In the Atlas UI, use the Registry Lab Core Public Service Vocabulary Application Profile (CPSV-AP) service catalogue demo chip, or enter http://127.0.0.1:4331/metadata/cpsv-ap.jsonld and open the Services tab.

Service topology

The compose file starts three Relay instances, four Notary instances, live Postgres and Zitadel services, a private OpenFn sidecar, a static metadata publisher, and a narrated demo client. For the full service inventory with host ports and network layout, see the Registry Lab reference.

Expected output

After step 5, all Relay and Notary services start in the background. scripts/smoke.sh runs more than 30 checks, including:

Health and readiness endpoints (/health, /ready) on all three Relay instances.
Discovery endpoint (/.well-known/evidence-service) on all three core Notary instances, with bearer-token and x-api-key coverage.
OpenAPI endpoints (/openapi.json) on all Relay and Notary instances.
Authorization scope denial responses (403 with auth.scope_denied) for out-of-scope credentials.
Positive row-read and aggregate-read responses on the social protection Relay.
Evidence evaluation (POST /claims/evaluate) on civil, social protection, and shared eligibility notaries.
A cross-authority claim result with source_count >= 2 on the shared eligibility notary.
Credential-bound evaluation returning application/dc+sd-jwt.
Audit log assertions, including a check that generated raw secrets are not emitted in service logs.

The demo client (step 7) runs three narrated scenarios and writes artifacts to output/. The Atlas inspection step (step 8) shows the health-linked child support public service, grouped Core Criterion and Core Evidence Vocabulary (CCCEV) evidence options, provider routes, and the linked form. All requests use the correlation ID decentralized-demo-correlation-001 by default (overridable via the DEMO_CORRELATION_ID environment variable).

Verify

Run scripts/smoke.sh as the primary verification command. A passing smoke run means all endpoint, authorization, audit, and credential checks pass.

To manually spot-check the static metadata publisher:

curl http://127.0.0.1:4331/metadata/index.json

The static publisher endpoints require no authentication.

Advanced: live services

These steps require sibling checkouts or live credentials and are not needed to verify the core topology. Run them after the smoke tests pass.

Run the OpenFn sidecar smoke path (requires a sibling registry-notary checkout):

env REGISTRY_OPENFN_NOTARY_SOURCE_DIR=../registry-notary \
    REGISTRY_NOTARY_SOURCE_DIR=../registry-notary \
    REGISTRY_PLATFORM_SOURCE_DIR=../registry-platform \
    scripts/smoke-openfn.sh

This writes output/smoke-openfn-notary-evaluation.json.

Run the live-service checks (Postgres cutover, Zitadel OIDC flow, OpenFn story, service-first discovery story):

scripts/check-relay-postgres.sh
scripts/check-relay-zitadel.sh
scripts/smoke-oidc-relay.sh
scripts/demo-live-stories.sh

These write artifacts to output/live-stories/.

Cleanup

Remove all containers and named cache volumes:

docker compose -f compose.yaml down -v

The -v flag removes the named volumes civil-registry-cache, social-protection-registry-cache, health-registry-cache, postgres-data, and zitadel-seed.