docs: expand Deployment guide (GitHub SSH, clone path, pg_restore, CppAlliance)

[snowfox1003]

Summary

• Document server-side SSH for git@github.com (separate from the GitHub Actions deploy key) and optional manual clone into /opt/boost-data-collector.
• Document copying boost_collector_schedule.yaml from the example alongside .env setup.
• Align deploy-user examples with CppAlliance (gcp-cppalliance).
• Document pg_restore as bdc over 127.0.0.1, clarify dump file readability and post-restore grants for postgres vs bdc restores.
• Reduce duplication: link “Updating .env” to Step 2 for ownership; point Docker stack at deploy-script behavior for CI’s make sequence.

Closes #186

The dev server is running on staging.insights.cppalliance.org.

Summary by CodeRabbit

• Documentation
  • Clarified GitHub Environments secret scope and updated required/optional secret guidance
  • Added server-side SSH key setup, host config, permission hardening, and verification steps
  • Expanded .env creation/update with Celery schedule template and sudo-safe chown/chmod guidance
  • Added manual repo checkout/ownership workflow and deploy-user ownership normalization
  • Clarified DB role/restore guidance including streaming and localhost/TCP alternative
  • Updated deploy sequencing, nginx example server names/cert paths, and generic port-forwarding placeholders

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3f6d6ea5-3de1-4dcc-a686-ef97327acafc

📥 Commits

Reviewing files that changed from the base of the PR and between d7dc21a and 17711ed.

📒 Files selected for processing (1)

• docs/Deployment.md

---

📝 Walkthrough

Walkthrough

Documentation-only updates to docs/Deployment.md revising GitHub environment secret wording, adding server SSH key instructions, expanding .env and Celery schedule creation/permissions, adding manual repository-init steps, refining PostgreSQL role text, expanding backup/restore options, and updating Docker/CI and nginx examples.

Changes

Deployment Guide Updates

Layer / File(s)	Summary
GitHub Environments / secrets wording and tables docs/Deployment.md	Clarifies required secrets are environment-scoped and updates the required/optional secrets tables and example SSH_USER wording (lines 24, 39–56).
Server SSH key for GitHub docs/Deployment.md	New section (lines 72–91) describing installing a dedicated server SSH key for git pull, recommended ~/.ssh/config Host stanza, permission hardening, and ssh -T verification.
Create .env and Celery beat schedule on server docs/Deployment.md	Expanded Step 2 (lines 104–123): explicit cp .env.example .env, copy/edit Celery beat schedule template, and chown/chmod 600 guidance when .env is created/edited with sudo; added reminder when updating .env (line 450).
Repository checkout and permissions docs/Deployment.md	Manual tree-prep and explicit git clone -b develop ... example (lines 158–195) for cases where the first CI deploy doesn't create /opt/boost-data-collector; ownership normalization guidance updated.
PostgreSQL role creation and CREATEDB note docs/Deployment.md	Reformatted role creation snippet to include a commented CREATE USER equivalent (lines 218–222) and clarified the app role does not require CREATEDB (line 232).
Backup and restore procedures docs/Deployment.md	Expanded restore guidance (lines 266–290): require least-privilege dump readability, add streaming restore example, add alternative TCP restore as bdc with PGPASSWORD/~/.pgpass notes, and clarify post-restore grants based on run-as user.
Docker stack / nginx examples and CI note docs/Deployment.md	State CI runs deploy targets in fixed order with make down first (line 330) and update nginx/URL-prefix examples to app.example.com with matching Let's Encrypt paths (lines 348–392).
Selenium SSH port-forwarding example docs/Deployment.md	Replace concrete example with generic placeholders YOUR_DEPLOY_USER@YOUR_SERVER_HOST (line 418).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• cppalliance/boost-data-collector#110: Related deployment workflow and docs updates tied to deploy.yml/deploy.sh and Deployment docs.
• cppalliance/boost-data-collector#130: Related changes to deployment examples, PostgreSQL setup, and nginx/reverse-proxy guidance.

Suggested labels

documentation

Suggested reviewers

• wpak-ai
• jonathanMLDev

Poem

🐰 I hopped through docs with careful paws,
Clarified secrets and tuned SSH laws,
Copied .env, locked keys with care,
Cloned the tree and fixed perms there —
Servers sing while I nibble applause!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main changes: expanding the Deployment guide with documentation about GitHub SSH setup, repository clone paths, pg_restore procedures, and CppAlliance conventions.
Linked Issues check	✅ Passed	The PR addresses issue #186 requirements: documents deployment steps for GCP staging environment, server SSH setup for git operations, Cloud SQL restore procedures, and CppAlliance deploy-user conventions.
Out of Scope Changes check	✅ Passed	All changes in docs/Deployment.md are directly aligned with issue #186 objectives: documenting server SSH usage, clone paths, pg_restore procedures, and environment setup for GCP staging deployment.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

docs/Deployment.md (1)

188-191: ⚡ Quick win

Avoid $USER in ownership commands for deploy docs.

Using $USER with sudo can resolve unexpectedly (for example, root shells), causing wrong ownership. Prefer the explicit deploy user placeholder (gcp-cppalliance) or an explicit <SSH_USER> placeholder consistently.

🤖 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/Deployment.md` around lines 188 - 191, Replace the unsafe use of "$USER"
in the ownership command: instead of sudo chown -R "$USER:$USER"
/opt/boost-data-collector, use an explicit deploy user placeholder (e.g.,
<SSH_USER>) or the concrete deploy account (e.g., gcp-cppalliance) so ownership
is deterministic; update the documentation text around the mkdir/chown sequence
(the lines containing sudo mkdir -p /opt/boost-data-collector and sudo chown -R
"$USER:$USER" /opt/boost-data-collector) to show sudo chown -R
<SSH_USER>:<SSH_USER> /opt/boost-data-collector (or
gcp-cppalliance:gcp-cppalliance) and ensure any surrounding instructions
reference the same placeholder.

🤖 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/Deployment.md`:
- Line 270: Replace the sentence that suggests placing dumps in /tmp with
world-readable permissions; instruct readers to use least-privilege permissions
and ownership instead: require the file be owned by the restoring account (e.g.,
the postgres OS user or the current login used for bdc/127.0.0.1) and set
restrictive mode like 600 (not 644), or store the dump in a secure directory or
stream it to pg_restore via stdin to avoid exposing sensitive backup contents.
Ensure references to pg_restore, /tmp/, 644, postgres, bdc and 127.0.0.1 in the
paragraph are updated accordingly.
- Around line 104-116: The copy/edit commands in Step 2 assume the current
working directory; prefix them by changing into the deployment directory first
to avoid failures—add an explicit cd to /opt/boost-data-collector at the start
of Step 2 so the subsequent cp .env.example .env and cp
config/boost_collector_schedule.yaml.example
config/boost_collector_schedule.yaml commands run from the correct repository
root.

---

Nitpick comments:
In `@docs/Deployment.md`:
- Around line 188-191: Replace the unsafe use of "$USER" in the ownership
command: instead of sudo chown -R "$USER:$USER" /opt/boost-data-collector, use
an explicit deploy user placeholder (e.g., <SSH_USER>) or the concrete deploy
account (e.g., gcp-cppalliance) so ownership is deterministic; update the
documentation text around the mkdir/chown sequence (the lines containing sudo
mkdir -p /opt/boost-data-collector and sudo chown -R "$USER:$USER"
/opt/boost-data-collector) to show sudo chown -R <SSH_USER>:<SSH_USER>
/opt/boost-data-collector (or gcp-cppalliance:gcp-cppalliance) and ensure any
surrounding instructions reference the same placeholder.

🪄 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: defaults

Review profile: CHILL

Plan: Pro

Run ID: bea3f151-d9a0-44eb-9510-b7b8aa1980ea

📥 Commits

Reviewing files that changed from the base of the PR and between 77bd37a and 63fa9c5.

📒 Files selected for processing (1)

• docs/Deployment.md