docs: Add production guide#302
Conversation
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
zeljkoX
added
documentation
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/guides/aws-signers/.env.example`:
- Around line 34-36: Reword the cursor signing key note in the .env.example
guidance so it does not claim the prod stage itself refuses to start; the
enforcement happens through Compose variable expansion in the docker-compose
setup. Update the comment near the pagination cursor secret description to match
this behavior, keeping the requirement for a 32-byte hex key but removing any
runtime-startup wording tied to prod.
In `@docs/guides/aws-signers/README.md`:
- Around line 65-67: The README wording for GUARDIAN_DASHBOARD_CURSOR_SECRET
should be updated because the current phrasing incorrectly implies the server
itself enforces the startup failure. Rephrase the explanation in the aws-signers
guide to make it clear that the immediate check happens in the Compose
required-variable validation driven by GUARDIAN_ENV=prod, and that this is what
blocks startup when the secret is missing.
In `@docs/guides/production/docker-compose.yml`:
- Line 24: The docker-compose service is publishing the metrics port externally
via the 9464 mapping, which exposes the endpoint on all interfaces by default.
Update the compose configuration for the affected service entries to bind
metrics to loopback only or remove the published port entirely, and keep the
change consistent across all referenced instances in the docker-compose file.
- Around line 19-20: The production docker compose service is defaulting to an
unstable image tag via the image field that references GUARDIAN_VERSION with a
latest fallback, which can cause non-reproducible deployments. Update the
compose configuration to require an explicit version tag for the guardian image
and remove the latest default from the image reference in the docker-compose
setup, keeping the change localized to the service definition that uses
pull_policy.
In `@docs/superpowers/specs/2026-06-24-production-guide-design.md`:
- Around line 17-25: The spec currently states an AWS-only scope and explicitly
says there is no committed Compose track, which conflicts with the new Docker
Compose deliverables. Update the scope/non-goals text in the production guide
spec to match the implemented `docs/guides/production/docker-compose.yml` and
related README content, using the existing “Scope” section and any references to
`PRODUCTION.md`/Compose so acceptance criteria are consistent.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 497b1ace-da82-47c9-9755-a3f8306bdef8
📒 Files selected for processing (9)
docs/PRODUCTION.mddocs/guides/README.mddocs/guides/aws-signers/.env.exampledocs/guides/aws-signers/README.mddocs/guides/aws-signers/docker-compose.ymldocs/guides/production/.env.exampledocs/guides/production/README.mddocs/guides/production/docker-compose.ymldocs/superpowers/specs/2026-06-24-production-guide-design.md
| # Required (GUARDIAN_ENV=prod): 32-byte hex (64 chars) signing key for dashboard | ||
| # pagination cursors. The prod stage refuses to start if this is unset. Generate: | ||
| # openssl rand -hex 32 |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Fix enforcement wording for missing cursor secret
Lines 35-36 currently imply the prod stage itself refuses startup. In this guide, the hard requirement is enforced by Compose variable expansion (see docs/guides/aws-signers/docker-compose.yml Line 45). Please reword to avoid runtime-behavior mismatch.
Suggested doc tweak
-# pagination cursors. The prod stage refuses to start if this is unset. Generate:
+# pagination cursors. This Compose stack requires it to be set before startup. Generate:📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| # Required (GUARDIAN_ENV=prod): 32-byte hex (64 chars) signing key for dashboard | |
| # pagination cursors. The prod stage refuses to start if this is unset. Generate: | |
| # openssl rand -hex 32 | |
| # Required (GUARDIAN_ENV=prod): 32-byte hex (64 chars) signing key for dashboard | |
| # pagination cursors. This Compose stack requires it to be set before startup. Generate: | |
| # openssl rand -hex 32 |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/guides/aws-signers/.env.example` around lines 34 - 36, Reword the cursor
signing key note in the .env.example guidance so it does not claim the prod
stage itself refuses to start; the enforcement happens through Compose variable
expansion in the docker-compose setup. Update the comment near the pagination
cursor secret description to match this behavior, keeping the requirement for a
32-byte hex key but removing any runtime-startup wording tied to prod.
There was a problem hiding this comment.
Pull request overview
Adds a new end-to-end “Production deployment” guide under docs/guides/production/, and wires it into the docs entry points so operators can follow a single step-by-step walkthrough from docs/PRODUCTION.md / docs/guides/README.md.
Changes:
- Add
docs/guides/production/README.mdplus a companion Compose stack and.env.example. - Link the new guide from
docs/PRODUCTION.mdand list it indocs/guides/README.md. - Update the existing
aws-signersguide’s Compose setup to include the dashboard cursor secret.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 22 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/superpowers/specs/2026-06-24-production-guide-design.md | Design/spec notes for the production guide deliverable and scope. |
| docs/PRODUCTION.md | Adds prominent link to the new production deployment guide and includes it in the “Where details live” table. |
| docs/guides/README.md | Adds the new Production deployment guide to the guides index and explains its artifacts. |
| docs/guides/production/README.md | New step-by-step production walkthrough (AWS ECS/Fargate + optional Compose track). |
| docs/guides/production/docker-compose.yml | New Compose stack for a self-hosted, single-replica run using AWS-managed secrets. |
| docs/guides/production/.env.example | Example environment file for the new production Compose track. |
| docs/guides/aws-signers/README.md | Documents the new required env var for the aws-signers Compose setup and points readers to the production guide. |
| docs/guides/aws-signers/docker-compose.yml | Adds GUARDIAN_DASHBOARD_CURSOR_SECRET to the aws-signers Compose environment. |
| docs/guides/aws-signers/.env.example | Adds GUARDIAN_DASHBOARD_CURSOR_SECRET to the aws-signers example env file. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #302 +/- ##
==========================================
+ Coverage 76.64% 76.95% +0.30%
==========================================
Files 155 160 +5
Lines 27745 28565 +820
==========================================
+ Hits 21264 21981 +717
- Misses 6481 6584 +103 Continue to review full report in Codecov by Harness.
🚀 New features to boost your workflow:
|
- Attribute cursor-secret enforcement to the Compose ${VAR:?} expansion rather
than a server-side prod guard (the server cursor secret is optional on main;
the hard requirement lands with #301).
- Production compose: require an explicit GUARDIAN_VERSION (drop the :latest
default) and bind the metrics port to loopback (127.0.0.1:9464).
- Track B smoke: drop the unconfirmed "storage encryption" log grep; rely on
ECDSA-signer-ready + clean startup.
- Remove the design-spec artifact from the PR (brainstorming doc, not repo
content).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Review responseFixed (valid regardless of merge order):
Copilot findings re: missing features (storage encryption envs/commands, |
The allowlist section now states there is no operator-key bootstrap (the server only holds operator public keys) and points at DASHBOARD.md "Enrolling an operator" for how an operator generates their own Falcon keypair. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Show both allowlist options: Terraform-managed from a public-key JSON list (dashboard:read only) vs. an externally-managed Secrets Manager secret via GUARDIAN_OPERATOR_PUBLIC_KEYS_SECRET_ARN (runtime _SECRET_ID), which is the only path that can grant accounts:pause via object entries. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Implements #299 — an end-to-end production deployment guide under
docs/guides/production/.This guide is written #301 (horizontal scaling)](#301) are merged**. It deliberately documents features not yet on
main:coordination mode=shared …startup log line,GUARDIAN_MAX_REPLICAS, and the prod-stage cursor-secret/filesystem guards (from feat: 010 scalability improvements #301).Automated reviewers (Copilot) flag these as "not in the codebase" — that is expected and by design. Each was cross-checked against the #293/#301 contracts and is correct for the post-merge world. This PR should merge only after #293 and #301 land.
Wording that is enforced by the committed Compose stacks (the
${VAR:?}cursor-secret check) rather than the server has been corrected to say so, so the Compose guides are accurate againstmaintoday.Summary by CodeRabbit
New Features
Documentation