eleven / messenger Public

--- name: deterministic-scripts-and-runbooks description: "Server tasks should produce idempotent scripts with runbooks, secrets go to 1Password" metadata: node_type: memory type: feedback originSessionId: 318046c9-35d3-4f60-9e34-90873f580290 ---

When doing server stuff (deployments, orchestration, bots, infrastructure), always produce a deterministic script that a human can run subsequently.

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.

How to apply:

1. Write scripts, not prose instructions: - Shell scripts (bash/fish) with extensive comments explaining each step - Include guard clauses (check prerequisites, fail early on missing env vars) - Document what the script does at the top (a usage block) - Make scripts idempotent where possible — running twice should be safe

1. Include warnings for destructive or risky steps: - Comment dangerous operations (rm, reset, force-push, schema changes) - Fail with a clear error if preconditions aren't met (e.g., "DB must have a backup before running this") - Prompt for confirmation before irreversible actions (optional, but encouraged)

1. Maintain a runbook in the relevant README: - Document common procedures (e.g., "How to deploy to production", "How to migrate an instance", "How to mint a new push relay token") - Link to or embed the scripts from version control - Include when/why you'd run each script, prerequisites, and rollback steps - Keep it updated as procedures change — a stale runbook is worse than no runbook

1. Secrets go to 1Password, documented in work summary: - Any secrets created (tokens, keys, credentials) must be stored in 1Password (Private vault, clearly named) - Include the 1Password item name/path in your work summary so the team knows where to find it - Document the secret's purpose and which services/instances use it - If you share a script that references a secret, explain how to retrieve it from 1Password (don't embed it)

Example: A deploy script might:

#!/bin/bash
set -e

# Deploy a new lchat version to production
# Usage: ./deploy-prod.sh <version>
# Prerequisites: SSH key for root@box, LCHAT_ADMIN_TOKEN in 1Password "lchat admin token (prod)"

VERSION="${1:?Error: must pass version}"
BOX="89.167.122.227"

echo "⚠️  Deploying $VERSION to production ($BOX)"
echo "This will restart all instances. Continue? (yes/no)"
read -r confirm
[[ "$confirm" == "yes" ]] || exit 1

# Copy binary to staging
scp lchat-linux-amd64 root@$BOX:/opt/lchat/incoming

# Stage and deploy with rollback on failure
ssh root@$BOX /opt/lchat/lchat stage --file /opt/lchat/incoming
ssh root@$BOX /opt/lchat/lchat deploy --all --version <ver> || {
  echo "Deploy failed. Rolling back all instances..."
  ssh root@$BOX /opt/lchat/lchat rollback --all
  exit 1
}

echo "✅ Deployed $VERSION successfully"

Work summary pattern: When you finish server work, include a section like:

## Secrets stored in 1Password
- Item: "lchat push relay token (new-instance.example.com)" — relay authentication token, needed for LCHAT_PUSH_RELAY_TOKEN env var
- Item: "lchat admin token (new-instance.example.com)" — admin link at https://new-instance.example.com/admin#token=...

## Scripts to run
- `./deploy-prod.sh v1.2.3` — deploys a new version to all instances (see docs/deploy-runbook.md for full procedure)

This transforms ad-hoc work into repeatable, auditable infrastructure code that the team can follow and improve.