docs: generic ops runbook and knowledge from production operations

[montoyaedu]

Summary

Lessons from running easy-proxy in production, written as tool knowledge. There are no deployment-specific details: hostnames, IPs, site/container names and host paths are kept out of the public repo. A new rule in CLAUDE.md makes this separation explicit.

• SERVER_RUNBOOK.md is rewritten as a generic runbook. It covers:

  • host layout;
  • versioning EASY_DOMAINS_DIR (yes) vs EASY_LETSENCRYPT_DIR (never);
  • choosing the ACME challenge by DNS provider;
  • HTTP-01 webroot for providers without a certbot plugin, including in-place conversion of a manual lineage;
  • automatic renewal (deploy hook + systemd timer);
  • connecting app stacks to the edge network;
  • troubleshooting.

• Knowledge base (.beads/knowledge/) gains these facts:

  • the templates lack WebSocket/ACME support;
  • Compose aliases collide on a shared edge network;
  • an explicit -f skips docker-compose.override.yml;
  • never put the letsencrypt dir under git;
  • HTTP-01 lineage conversion;
  • renewal via hook + timer, and orphan lineages failing certbot renew;
  • the IONOS key format.

  It also corrects the wildcard decision: certbot-dns-ionos does not follow CNAME delegation (zone lookup is by suffix match on the cert domain), and /var/www/certbot is not served by any template.

• STATE.md now covers tool state only. The roadmap gains certbot-webroot, renew, WebSocket/ACME templates, and doctor checks.

• Fixes stale ~/ethiclab/lab/easy-proxy paths in CLAUDE.md, AGENTS.md and UC1_LOCAL_SSL_SETUP.md.

Docs and knowledge base only, no code changes.

Test plan

• bats test/: 55/55
• Scanned the diff for deployment-specific strings (hosts, IPs, container names, host paths): none left
• CI lint/test green

🤖 Generated with Claude Code

https://claude.ai/code/session_01UjwTpRz63tgAMuiPpthK1B