# 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**
   ```bash
   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**
   ```bash
   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**
   ```bash
   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`.

4. **Smoke test**
   ```bash
   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**
   ```bash
   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**
   ```bash
   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**
   ```bash
   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**
   ```bash
   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.