docs: reshuffle README around tasks; split quickstart into deployment + ops#9
Merged
Conversation
… + ops Reorient the project's front door around the four tasks a new reader actually has: understand what hooks is, deploy the server, use hooksctl, contribute (including adding new providers). Lead the deploy section with the Docker path, since that's the supported shape. Split the single quickstart into two reference docs: - docs/quickstart.md → docs/deployment.md (env vars, `hooks init` flags, container internals, Render Blueprint specifics, skew-window semantics). One-time setup reference. - docs/operations.md → docs/running-in-production.md (backups, retention, observability, push-subscription health, restarts and signing-secret state, graceful shutdown). Day-2 ops. The split is clean — the two docs cover disjoint topics, and the README cross-references each at the right seam. Specifics worth calling out, accumulated across two review rounds: - "Try it locally first" exports RENDER_WEBHOOK_SECRET (without it `./bin/hooks` fails immediately with "empty secret") and points the reader at `hooksctl tail` and the inspector URL so they can verify the setup is working. Notes the password policy (≥ 12 chars, no email substring) so signup doesn't bounce them to accounts.md. - `make dev` is described accurately: it uses the configured listen addr (default :8080), not a random free port, and does not run init. - Section 2 leads with a pointer to docs/accounts.md as the full developer-onboarding walkthrough, not the admin-ops afterthought. - The "admin token" is described as a system-level credential that predates the user-account system, not a "legacy" credential. - Option B opens with "export RENDER_WEBHOOK_SECRET first" so the `-e` passthrough has a value. TLS-terminator reminders consolidated to the canonical mention at the top of the page. - `hooksctl replay` example takes the positional <seq> and --to URL. - rotate-secret callout distinguishes `me sub` (self) from `push` (admin-wide) for restart recovery. - Provider section collapsed to a teaser + pointer to docs/sources.md, with Stripe/GitHub/Vercel as illustrative examples and the --profile flag mentioned inline. - accounts.md cross-references repointed; example hostnames aligned on webhooks.example.com; password-policy wording tightened to match the ≥ 3-char local-part gate in internal/users/policy.go. - running-in-production.md explains the `me sub *` vs `push *` split and shows `hooksctl push test` for smoke-testing a consumer. Clarifies that `/push` is an inspector page. - deployment.md: admin token's *plaintext* is unrecoverable (the Argon2id hash lives in the DB); --token-name added to the init-flags list; "Useful flags" renamed to "Notable flags" so the list isn't misread as exhaustive. - render.yaml header comment repointed at the README's Option A.
📝 WalkthroughWalkthroughThe PR restructures user-facing documentation by removing the standalone quickstart guide, consolidating its content into a redesigned README with new "Try it locally first" and "Deploy the server" sections, introducing a comprehensive ChangesDocumentation Reorganization and Deployment Reference
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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/accounts.md`:
- Around line 15-19: The fenced code block in docs/accounts.md is missing a
language specifier which prevents proper rendering; update the triple-backtick
opening fence for the block that starts with "admin token (shown ONCE): <legacy
system token, copy if you want one>" to include a language identifier (e.g., use
```text or ```console) so the snippet renders correctly.
🪄 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 Plus
Run ID: ac69f183-73a2-4328-8e72-cba4d42e2fa5
📒 Files selected for processing (6)
README.mddocs/accounts.mddocs/deployment.mddocs/quickstart.mddocs/running-in-production.mdrender.yaml
💤 Files with no reviewable changes (1)
- docs/quickstart.md
Comment on lines
15
to
19
| ``` | ||
| admin token (shown ONCE): <legacy system token, copy if you want one> | ||
| signup: https://hooks.example.com/signup?code=ABCDEFGH... | ||
| signup: https://webhooks.example.com/signup?code=ABCDEFGH... | ||
| (single-use; expires in 24h; auto-disables once any account exists) | ||
| ``` |
There was a problem hiding this comment.
Add language specifier to fenced code block.
The code block should specify a language identifier for proper rendering. Since this is output text from the hooks init command, text or console would be appropriate.
📝 Proposed fix
-```
+```text
admin token (shown ONCE): <legacy system token, copy if you want one>
signup: https://webhooks.example.com/signup?code=ABCDEFGH...
(single-use; expires in 24h; auto-disables once any account exists)</details>
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.22.1)</summary>
[warning] 15-15: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
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/accounts.md around lines 15 - 19, The fenced code block in
docs/accounts.md is missing a language specifier which prevents proper
rendering; update the triple-backtick opening fence for the block that starts
with "admin token (shown ONCE): <legacy system token, copy if you want one>" to
include a language identifier (e.g., use text or console) so the snippet
renders correctly.
</details>
<!-- fingerprinting:phantom:triton:puma -->
<!-- d98c2f50 -->
<!-- This is an auto-generated comment by CodeRabbit -->
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
1 participant
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.
Reorient the project's front door around the four tasks a new reader actually has: understand what hooks is, deploy the server, use hooksctl, contribute (including adding new providers). Lead the deploy section with the Docker path, since that's the supported shape.
Split the single quickstart into two reference docs:
hooks initflags, container internals, Render Blueprint specifics, skew-window semantics). One-time setup reference.The split is clean — the two docs cover disjoint topics, and the README cross-references each at the right seam.
Specifics worth calling out, accumulated across two review rounds:
./bin/hooksfails immediately with "empty secret") and points the reader athooksctl tailand the inspector URL so they can verify the setup is working. Notes the password policy (≥ 12 chars, no email substring) so signup doesn't bounce them to accounts.md.make devis described accurately: it uses the configured listen addr (default :8080), not a random free port, and does not run init.-epassthrough has a value. TLS-terminator reminders consolidated to the canonical mention at the top of the page.hooksctl replayexample takes the positional and --to URL.me sub(self) frompush(admin-wide) for restart recovery.me sub *vspush *split and showshooksctl push testfor smoke-testing a consumer. Clarifies that/pushis an inspector page.Summary by CodeRabbit