From ce7a3a306ef8b2983d04690a6f5f752447836dd1 Mon Sep 17 00:00:00 2001 From: shankar0123 Date: Tue, 5 May 2026 20:55:26 +0000 Subject: [PATCH] docs: fix broken single-file demo invocation in README + qa-prerequisites + ENVIRONMENTS MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README's Quick Start, the qa-prerequisites contributor doc, and the landing page (separate repo, separate commit) all shipped a copy-paste command that produces: service "certctl-server" has neither an image nor a build context specified: invalid compose project The bug landed silently with commit df4b567 (the U-3 master). Pre-U-3, docker-compose.demo.yml was self-contained and could be invoked with a single -f flag. U-3 deliberately reduced it to a 27-line overlay — its only payload today is `CERTCTL_DEMO_SEED=true` on the certctl-server service — because the demo seed now applies at boot via postgres.RunDemoSeed, not via /docker-entrypoint-initdb.d/. The overlay no longer carries an image: or build: of its own, so it MUST be passed alongside the base file. The README/qa-doc/landing-page never picked up the rename of the contract. Every operator who copy-pasted the Quick Start since U-3 has hit the "invalid compose project" error and bounced. The operator caught it running the demo locally today. This commit fixes the three certctl-repo sites: README.md (Quick Start) docker compose -f deploy/docker-compose.demo.yml up -d --build → docker compose -f deploy/docker-compose.yml -f deploy/docker-compose.demo.yml up -d --build Plus the "drop the -f flag for clean install" prose now spells out the correct fallback (`-f deploy/docker-compose.yml` alone). docs/contributor/qa-prerequisites.md (Step 1) Same single-file → two-file fix, plus an inline note explaining why the override-only file requires the base (so the next person who reads it understands the contract instead of re-discovering it). deploy/ENVIRONMENTS.md (Demo Overlay → What it adds) Replaced the stale "One line: mounts seed_demo.sql into PostgreSQL's init directory" claim — that hasn't been true since U-3 — with the accurate "One env var: CERTCTL_DEMO_SEED=true; server applies seed_demo.sql at boot via postgres.RunDemoSeed" description, plus the historical context for why the overlay can't stand alone. The certctl.io landing page hits the same bug (line 759); fix shipping in a separate commit in that repo. Acceptance gate (manual): - copy/paste the new README Quick Start command end-to-end against a fresh clone — succeeds, dashboard at https://localhost:8443 shows the seeded demo data within ~30s. - clean-install fallback (`docker compose -f deploy/docker-compose.yml up -d --build`) starts a working stack with no demo data. --- README.md | 6 +++--- deploy/ENVIRONMENTS.md | 4 +++- docs/contributor/qa-prerequisites.md | 4 ++-- 3 files changed, 8 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index a1f6534..b88c500 100644 --- a/README.md +++ b/README.md @@ -81,12 +81,12 @@ Security: API key auth enforced by default with SHA-256 hashing and constant-tim ```bash git clone https://github.com/certctl-io/certctl.git cd certctl -docker compose -f deploy/docker-compose.demo.yml up -d --build +docker compose -f deploy/docker-compose.yml -f deploy/docker-compose.demo.yml up -d --build ``` -Wait ~30 seconds, then open **https://localhost:8443** in your browser. The shipped demo override seeds 32 certificates across 10 issuers, 8 agents, and 180 days of realistic history. The `certctl-tls-init` init container self-signs an ECDSA-P256 cert on first boot — accept the browser warning for the demo, or feed the generated `ca.crt` to your client. +Wait ~30 seconds, then open **https://localhost:8443** in your browser. The shipped demo overlay seeds 32 certificates across 10 issuers, 8 agents, and 180 days of realistic history. The `certctl-tls-init` init container self-signs an ECDSA-P256 cert on first boot — accept the browser warning for the demo, or feed the generated `ca.crt` to your client. -For a clean install without demo data, drop the `-f deploy/docker-compose.demo.yml` flag. The four compose files (`docker-compose.yml` base, `docker-compose.demo.yml` overlay, `docker-compose.dev.yml` for PgAdmin + debug logging, `docker-compose.test.yml` for integration tests) are documented at [`deploy/ENVIRONMENTS.md`](deploy/ENVIRONMENTS.md). +For a clean install without demo data, drop the `-f deploy/docker-compose.demo.yml` flag and run `docker compose -f deploy/docker-compose.yml up -d --build`. The four compose files (`docker-compose.yml` base, `docker-compose.demo.yml` overlay, `docker-compose.dev.yml` for PgAdmin + debug logging, `docker-compose.test.yml` for integration tests) are documented at [`deploy/ENVIRONMENTS.md`](deploy/ENVIRONMENTS.md). ```bash curl --cacert $(docker compose -f deploy/docker-compose.yml exec -T certctl-server cat /etc/certctl/tls/ca.crt) https://localhost:8443/health diff --git a/deploy/ENVIRONMENTS.md b/deploy/ENVIRONMENTS.md index c4e46f1..d53fc76 100644 --- a/deploy/ENVIRONMENTS.md +++ b/deploy/ENVIRONMENTS.md @@ -198,7 +198,9 @@ docker compose -f deploy/docker-compose.yml down -v ### What it adds -One line: mounts `seed_demo.sql` into PostgreSQL's init directory. This 667-line SQL file inserts 180 days of simulated operational history: teams, owners, certificates across multiple issuers, agents on different platforms, jobs with realistic timestamps, discovery scan results, audit events, policies, and profiles. +One env var: `CERTCTL_DEMO_SEED=true` on the `certctl-server` service. The server applies `migrations/seed_demo.sql` at boot via `postgres.RunDemoSeed` AFTER the baseline migrations + `seed.sql` are in place. The demo seed file inserts 180 days of simulated operational history: teams, owners, certificates across multiple issuers, agents on different platforms, jobs with realistic timestamps, discovery scan results, audit events, policies, and profiles. + +Pre-U-3 the overlay used to mount `seed_demo.sql` into PostgreSQL's `/docker-entrypoint-initdb.d/` and rely on initdb-time application. That worked only because the production stack also mounted the migrations there, so the schema existed when initdb ran. Once U-3 dropped the production initdb mounts (single source of truth: server runs `RunMigrations` + `RunSeed` at boot), the demo seed could no longer be applied at initdb time — the tables it references wouldn't exist yet. Post-U-3 the overlay is a 27-line override file with no `image:` / `build:` of its own; it MUST be passed alongside the base, or compose errors with `service "certctl-server" has neither an image nor a build context specified`. ### Starting it diff --git a/docs/contributor/qa-prerequisites.md b/docs/contributor/qa-prerequisites.md index 9ca00ef..bab41cb 100644 --- a/docs/contributor/qa-prerequisites.md +++ b/docs/contributor/qa-prerequisites.md @@ -13,10 +13,10 @@ Automated tests mock dependencies and run in isolation. Manual QA validates the **Step 1: Start the full stack.** ```bash -cd deploy && docker compose -f docker-compose.demo.yml up --build -d +cd deploy && docker compose -f docker-compose.yml -f docker-compose.demo.yml up --build -d ``` -This builds three containers (postgres, certctl-server, certctl-agent) and runs them on a bridge network. The `--build` flag ensures you're testing the current code, not a stale image. The `demo` overlay seeds the database with realistic fixtures. +This builds three containers (postgres, certctl-server, certctl-agent) and runs them on a bridge network. The `--build` flag ensures you're testing the current code, not a stale image. The `demo` overlay is an override file (no `image:` or `build:` of its own) that layers `CERTCTL_DEMO_SEED=true` onto the base — both files must be passed in that order or compose errors with `service "certctl-server" has neither an image nor a build context specified`. The seed populates the database with realistic fixtures. **Step 2: Wait for healthy state.**