mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 14:11:31 +00:00
docs: fix broken single-file demo invocation in README + qa-prerequisites + ENVIRONMENTS
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 a3d8b9c (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.
This commit is contained in:
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user