git.stella-ops.org/docs/modules/issuer-directory/operations/deployment.md

Issuer Directory Deployment Guide

Scope

• Applies to: Issuer Directory WebService (stellaops/issuer-directory-web) running via the provided Docker Compose bundles (deploy/compose/docker-compose.*.yaml) or the Helm chart (deploy/helm/stellaops).
• Covers: Environment prerequisites, secret handling, Compose + Helm rollout steps, and post-deploy verification.
• Audience: Platform/DevOps engineers responsible for Identity & Signing sprint deliverables.

1 · Prerequisites

• Authority must be running and reachable at the issuer URL you configure (default Compose host: https://authority:8440).
• MongoDB 4.2+ with credentials for the issuer-directory database (Compose defaults to the root user defined in .env).
• Network access to Authority, MongoDB, and (optionally) Prometheus if you scrape metrics.
• Issuer Directory configuration file etc/issuer-directory.yaml checked and customised for your environment (tenant header, audiences, telemetry level, CSAF seed path).

Secrets: Use etc/secrets/issuer-directory.mongo.secret.example as a template. Store the real connection string in an untracked file or secrets manager and reference it via environment variables (ISSUER_DIRECTORY_MONGO_CONNECTION_STRING) rather than committing credentials.

2 · Deploy with Docker Compose

1. Prepare environment variables

   cp deploy/compose/env/dev.env.example dev.env
   cp etc/secrets/issuer-directory.mongo.secret.example issuer-directory.mongo.env
   # Edit dev.env and issuer-directory.mongo.env with production-ready secrets.
   

2. Inspect the merged configuration

   docker compose \
     --env-file dev.env \
     --env-file issuer-directory.mongo.env \
     -f deploy/compose/docker-compose.dev.yaml config
   

   The command confirms the new issuer-directory service resolves the port (${ISSUER_DIRECTORY_PORT:-8447}) and the Mongo connection string is in place.

3. Launch the stack

   docker compose \
     --env-file dev.env \
     --env-file issuer-directory.mongo.env \
     -f deploy/compose/docker-compose.dev.yaml up -d issuer-directory
   

   Compose automatically mounts ../../etc/issuer-directory.yaml into the container at /etc/issuer-directory.yaml, seeds CSAF publishers, and exposes the API on https://localhost:8447.

Compose environment variables

Variable	Purpose	Default
ISSUER_DIRECTORY_PORT	Host port that maps to container port 8080.	8447
ISSUER_DIRECTORY_MONGO_CONNECTION_STRING	Injected into ISSUERDIRECTORY__MONGO__CONNECTIONSTRING; should contain credentials.	mongodb://${MONGO_INITDB_ROOT_USERNAME}:${MONGO_INITDB_ROOT_PASSWORD}@mongo:27017
ISSUER_DIRECTORY_SEED_CSAF	Toggles CSAF bootstrap on startup. Set to false after the first production import if you manage issuers manually.	true

4. Smoke test

   curl -k https://localhost:8447/health/live
   stellaops-cli issuer-directory issuers list \
     --base-url https://localhost:8447 \
     --tenant demo \
     --access-token "$(stellaops-cli auth token issue --scope issuer-directory:read)"
   

5. Upgrade & rollback

   • Update Compose images to the desired release manifest (deploy/releases/*.yaml), re-run docker compose config, then docker compose up -d.
   • Rollbacks follow the same steps with the previous manifest. Mongo collections are backwards compatible within 2025.10.x.

3 · Deploy with Helm

1. Create or update the secret

   kubectl create secret generic issuer-directory-secrets \
     --from-literal=ISSUERDIRECTORY__MONGO__CONNECTIONSTRING='mongodb://stellaops:<password>@stellaops-mongo:27017' \
     --dry-run=client -o yaml | kubectl apply -f -
   

   Add optional overrides (e.g. ISSUERDIRECTORY__AUTHORITY__ISSUER) if your Authority issuer differs from the default.

2. Template for validation

   helm template issuer-directory deploy/helm/stellaops \
     -f deploy/helm/stellaops/values-prod.yaml \
     --set services.issuer-directory.env.ISSUERDIRECTORY__AUTHORITY__ISSUER=https://authority.prod.stella-ops.org \
     > /tmp/issuer-directory.yaml
   

3. Install / upgrade

   helm upgrade --install stellaops deploy/helm/stellaops \
     -f deploy/helm/stellaops/values-prod.yaml \
     --set services.issuer-directory.env.ISSUERDIRECTORY__AUTHORITY__ISSUER=https://authority.prod.stella-ops.org
   

   The chart provisions:

   • ConfigMap stellaops-issuer-directory-config with IssuerDirectory settings.
   • Deployment stellaops-issuer-directory with readiness/liveness probes on /health/live.
   • Service on port 8080 (ClusterIP by default).

4. Expose for operators (optional)

   • Use an Ingress/HTTPRoute to publish https://issuer-directory.<env>.stella-ops.org.
   • Ensure the upstream includes DPoP headers if proxied through an API gateway.

5. Post-deploy validation

   kubectl exec deploy/stellaops-issuer-directory -- \
     curl -sf http://127.0.0.1:8080/health/live
   kubectl logs deploy/stellaops-issuer-directory | grep 'IssuerDirectory Mongo connected'
   

   Prometheus should begin scraping issuer_directory_changes_total and related metrics (labels: tenant, issuer, action).

4 · Operational checklist

• Secrets: Connection strings live in issuer-directory-secrets (Helm) or an .env file stored in your secrets vault (Compose). Rotate credentials via secret update + pod restart.
• Audit streams: Confirm issuer_directory_audit collection receives entries when CRUD operations run; export logs for compliance.
• Tenants: The service enforces the X-StellaOps-Tenant header. For multi-tenant staging, configure the reverse proxy to inject the correct tenant or issue scoped tokens.
• CSAF seeds: ISSUER_DIRECTORY_SEED_CSAF=true replays data/csaf-publishers.json on startup. Set to false once production tenants are fully managed, or override csafSeedPath with a curated bundle.
• Release alignment: Before promotion, run deploy/tools/validate-profiles.sh to lint Compose/Helm bundles, then verify the new issuer-directory-web entry in deploy/releases/2025.10-edge.yaml (or the relevant manifest) matches the channel you intend to ship.