Repository navigation
docs: admin console guide and generated config reference - #1502
Merged
Merged
Conversation
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The demo has unsafe cleanup behavior and broken or misleading operator documentation.
11 open findings
What changed in this PR
Adds operator documentation, generated configuration references, and a disposable demo for the in-process verifier admin console.
Changes:
- Documents console setup, safety, recovery, and runbook workflows.
- Registers generated admin-console configuration documentation.
- Adds a seeded Postgres demo with a canned aggregator client.
| File | Description |
|---|---|
.gitignore |
Ignores demo runtime artifacts. |
changelog/2026-09-23_admin_console.md |
Records the admin-console feature. |
cli/recovery/README.md |
Links recovery CLI users to the console. |
docs/config/README.md |
Lists the console config reference. |
docs/config/admin-console/config.documented.toml |
Provides generated config documentation. |
docs/runbooks/remediating-stuck-or-dropped-messages.md |
Makes the console the primary recovery path. |
docs/verifier/admin-console.md |
Adds the operator guide. |
docs/verifier/admin-console-demo/README.md |
Documents the demo walkthrough. |
docs/verifier/admin-console-demo/demo-config.toml |
Configures the demo console. |
docs/verifier/admin-console-demo/demo.sh |
Starts and tears down the demo. |
docs/verifier/admin-console-demo/main.go |
Implements the demo harness. |
docs/verifier/admin-console-demo/seed-verifier.sql |
Seeds representative verifier data. |
tools/configdoc/registry/registry.go |
Registers console config generation. |
verifier/pkg/admin/doccomments_gen.go |
Supplies generated field documentation. |
Files not reviewed (1)
- verifier/pkg/admin/doccomments_gen.go: Generated file
🧠 Review effort: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+35
to
+36
| pid="$(cat "$pidfile")" | ||
| if kill "$pid" 2>/dev/null; then |
Contributor
Author
There was a problem hiding this comment.
Done — stop() now signals a PID only while ps -p <pid> still reports this demo's console-demo process, waits for it to exit before removing the PID file, and only then re-checks the port (the next start re-runs port_free as before).
| start() { | ||
| command -v docker >/dev/null || die "docker is required" | ||
| docker info >/dev/null 2>&1 || die "docker daemon is not running" | ||
| command -v nc >/dev/null || die "nc is required (port checks)" |
Contributor
Author
There was a problem hiding this comment.
Done — command -v curl is checked with the other prerequisites and fails fast with the actual missing-binary error.
Comment on lines
+58
to
+61
| docker run -d --name "$CONTAINER" \ | ||
| -e POSTGRES_USER="$PG_USER" -e POSTGRES_PASSWORD="$PG_PASSWORD" \ | ||
| -e POSTGRES_DB="$VERIFIER_DB" \ | ||
| -p 127.0.0.1:"$PG_PORT":5432 postgres:15-alpine >/dev/null |
Contributor
Author
There was a problem hiding this comment.
Done — start() installs an EXIT trap that calls stop on any non-zero exit during startup (a successful start keeps everything running). Verified: a deliberately failing seed exits non-zero and leaves no container or harness behind.
|  | ||
|
|
||
| Prerequisites: Docker (running), Go, nc. |
Contributor
Author
There was a problem hiding this comment.
Done — curl is listed in the quick-start prerequisites.
Comment on lines
+2
to
+7
| # One-command demo of the CCV admin console. See README.md for the walkthrough. | ||
| # | ||
| # start (default) : disposable Postgres, seeded demo data, and the console harness | ||
| # (the real admin package, served in-process) on http://127.0.0.1:8105 | ||
| # stop : stop the console harness, remove the container | ||
| # clean : stop and also delete .runtime/ |
Contributor
Author
There was a problem hiding this comment.
Condensed to three lines (shebang aside).
Comment on lines
+1
to
+5
| // Command admin-console-demo is the harness for the admin console demo (see README.md | ||
| // in this directory): it serves the real admin console (verifier/pkg/admin) over a | ||
| // seeded disposable database, the same way the verifier factory serves it in-process. | ||
| // A canned aggregator results client stands in for the aggregator's attestation read | ||
| // API so the reschedule gate can be shown without real infrastructure. |
Contributor
Author
There was a problem hiding this comment.
Condensed to three lines.
Comment on lines
+1
to
+7
| -- Demo data for the verifier database. demo.sh runs this after the console harness | ||
| -- has started (it applies the verifier migrations, action-log table included, at | ||
| -- startup). | ||
| -- Message IDs are 8x8 repeats so they are easy to read out and type into search: | ||
| -- 0xdeadbeef x8 -> attested (the harness's canned aggregator holds ccv data) | ||
| -- 0xcafebabe x8 -> not attested (executable reschedule target; has drop evidence) | ||
| -- 0x0badf00d x8 -> retry window expired (detail page shows the expiry state) |
Contributor
Author
There was a problem hiding this comment.
Condensed to three lines; the per-chain legend below it was already short and stays.
Comment on lines
+61
to
+66
| -- Failed archive rows the search and reschedule flows read. Categories are derived | ||
| -- at read time from these values (see verifier/pkg/jobqueue/archivecategory): | ||
| -- policy hook rejected... -> policy_rejected | ||
| -- source chain selector... not configured -> validation_error | ||
| -- storage-writer table -> storage_failure | ||
| -- completed_at >= retry_deadline -> retry_window_expired |
Contributor
Author
There was a problem hiding this comment.
Condensed to three lines.
Comment on lines
+95
to
+97
| `check-config` runs the same loading and validation as startup and prints the listen | ||
| address and access mode. Run it after every config change — it catches misspelled keys | ||
| and malformed files before the verifier does it at startup. |
Contributor
Author
There was a problem hiding this comment.
Done in the wiring PR (#1501): check-config now receives the CLI-loaded verifier secrets and runs the same BasicAuthFromSecrets + ValidateAccessPolicy validation as console startup; this PR updates the guide's pre-flight section to match.
makramkd
approved these changes
Oct 8, 2026
carte7000
approved these changes
Oct 8, 2026
github-merge-queue
Bot
removed this pull request from the merge queue because a pull request earlier in the stack was removed
Oct 8, 2026
github-merge-queue
Bot
removed this pull request from the merge queue due to failed status checks
Oct 8, 2026
|
Code coverage report:
Files added (in
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Top of a 3-PR stack splitting #1471 (base: #1501):
docs/verifier/admin-console.md— rewritten for the in-process, single-verifier model (noccv admin serve, no console DB, no read-only mode).tools/configdoctarget for the admin console config, sodocs/config/admin-console/config.documented.tomlis generated like every other app (removes the hand-written exception fromdocs/config/README.md).docs/verifier/admin-console-demo/— one-command disposable demo, reworked for the in-process model: a small harness (main.go) serves the real admin package over a seeded disposable Postgres, with a canned aggregator results client injected viaadmin.Deps.ResultsDialer. Verified end-to-end (search, gated reschedule, recovery preview, action log).Stack: #1500 → #1501 → this PR.