| 1 | --- |
| 2 | name: deterministic-scripts-and-runbooks |
| 3 | description: "Server tasks should produce idempotent scripts with runbooks, secrets go to 1Password" |
| 4 | metadata: |
| 5 | node_type: memory |
| 6 | type: feedback |
| 7 | originSessionId: 318046c9-35d3-4f60-9e34-90873f580290 |
| 8 | --- |
| 9 | |
| 10 | **When doing server stuff (deployments, orchestration, bots, infrastructure), always produce a deterministic script that a human can run subsequently.** |
| 11 | |
| 12 | **Why:** Server changes are high-risk and need to be repeatable, auditable, and separable from ad-hoc CLI decisions. Scripts let team members reproduce your work, reduce manual error, and make deployment reversible. |
| 13 | |
| 14 | **How to apply:** |
| 15 | |
| 16 | 1. **Write scripts, not prose instructions:** |
| 17 | - Shell scripts (bash/fish) with extensive comments explaining each step |
| 18 | - Include guard clauses (check prerequisites, fail early on missing env vars) |
| 19 | - Document what the script does at the top (a usage block) |
| 20 | - Make scripts idempotent where possible — running twice should be safe |
| 21 | |
| 22 | 2. **Include warnings for destructive or risky steps:** |
| 23 | - Comment dangerous operations (`rm`, `reset`, force-push, schema changes) |
| 24 | - Fail with a clear error if preconditions aren't met (e.g., "DB must have a backup before running this") |
| 25 | - Prompt for confirmation before irreversible actions (optional, but encouraged) |
| 26 | |
| 27 | 3. **Maintain a runbook in the relevant README:** |
| 28 | - Document common procedures (e.g., "How to deploy to production", "How to migrate an instance", "How to mint a new push relay token") |
| 29 | - Link to or embed the scripts from version control |
| 30 | - Include when/why you'd run each script, prerequisites, and rollback steps |
| 31 | - Keep it updated as procedures change — a stale runbook is worse than no runbook |
| 32 | |
| 33 | 4. **Secrets go to 1Password, documented in work summary:** |
| 34 | - Any secrets created (tokens, keys, credentials) must be stored in 1Password (Private vault, clearly named) |
| 35 | - Include the 1Password item name/path in your work summary so the team knows where to find it |
| 36 | - Document the secret's purpose and which services/instances use it |
| 37 | - If you share a script that references a secret, explain how to retrieve it from 1Password (don't embed it) |
| 38 | |
| 39 | **Example:** A deploy script might: |
| 40 | ```bash |
| 41 | #!/bin/bash |
| 42 | set -e |
| 43 | |
| 44 | # Deploy a new lchat version to production |
| 45 | # Usage: ./deploy-prod.sh <version> |
| 46 | # Prerequisites: SSH key for root@box, LCHAT_ADMIN_TOKEN in 1Password "lchat admin token (prod)" |
| 47 | |
| 48 | VERSION="${1:?Error: must pass version}" |
| 49 | BOX="89.167.122.227" |
| 50 | |
| 51 | echo "⚠️ Deploying $VERSION to production ($BOX)" |
| 52 | echo "This will restart all instances. Continue? (yes/no)" |
| 53 | read -r confirm |
| 54 | [[ "$confirm" == "yes" ]] || exit 1 |
| 55 | |
| 56 | # Copy binary to staging |
| 57 | scp lchat-linux-amd64 root@$BOX:/opt/lchat/incoming |
| 58 | |
| 59 | # Stage and deploy with rollback on failure |
| 60 | ssh root@$BOX /opt/lchat/lchat stage --file /opt/lchat/incoming |
| 61 | ssh root@$BOX /opt/lchat/lchat deploy --all --version <ver> || { |
| 62 | echo "Deploy failed. Rolling back all instances..." |
| 63 | ssh root@$BOX /opt/lchat/lchat rollback --all |
| 64 | exit 1 |
| 65 | } |
| 66 | |
| 67 | echo "✅ Deployed $VERSION successfully" |
| 68 | ``` |
| 69 | |
| 70 | **Work summary pattern:** When you finish server work, include a section like: |
| 71 | ``` |
| 72 | ## Secrets stored in 1Password |
| 73 | - Item: "lchat push relay token (new-instance.example.com)" — relay authentication token, needed for LCHAT_PUSH_RELAY_TOKEN env var |
| 74 | - Item: "lchat admin token (new-instance.example.com)" — admin link at https://new-instance.example.com/admin#token=... |
| 75 | |
| 76 | ## Scripts to run |
| 77 | - `./deploy-prod.sh v1.2.3` — deploys a new version to all instances (see docs/deploy-runbook.md for full procedure) |
| 78 | ``` |
| 79 | |
| 80 | This transforms ad-hoc work into repeatable, auditable infrastructure code that the team can follow and improve. |
| 81 | |
amadan