homelabstack/AGENTS.md

AGENTS.md

Project context for AI coding agents (Codex, Antigravity, and any agent that reads AGENTS.md).

The canonical instructions for this repo live in CLAUDE.md. Read it first — this file is a thin pointer plus the must-know essentials so nothing is missed if the reference isn't chased. Global cross-project rules (identity, Obsidian vault as source of truth, Gitea-first) come from your tool's user-level instructions (~/.codex/AGENTS.md / ~/.gemini/GEMINI.md).

Essentials (full detail in CLAUDE.md)

• What this is: deployment config for a live, single-host Docker homelab on a headless Ubuntu server reachable at ssh ginnoir@valhalla. ~50 containers in per-domain Portainer-managed stacks. This is not application code.
• The repo is canonical. Portainer polls main every 5 min and redeploys any app stack whose stacks/<domain>/* files changed. Editing here changes nothing until you git push.
• Deployment channels:
  • stacks/<domain>/* → git push → Portainer redeploys that stack (≤ 5 min).
  • Caddyfile → git push → runner workflow scps it + reloads Caddy (or apply-compose.ps1 -Caddy).
  • portainer-compose.yml / vault.hcl → apply-compose.ps1 -Portainer (Portainer can't manage itself).
• Secrets are committed intentionally. .env and stacks/*/stack.env are versioned in this PRIVATE repo. Do not scrub or gitignore them.
• Line endings: .gitattributes forces LF. Never push CRLF (especially stack.env) — stray \r breaks values on the Linux host.
• Networks: edge is the only reverse-proxy network (Caddy + anything it proxies); <domain> nets are per-stack private. Caddy upstreams use container name + container-internal port.
• Live ops: there is no dc alias — address services by container name with plain docker over SSH, or use the portainer MCP server.

See CLAUDE.md for the on-host topology, "adding a service" steps, Caddyfile/TLS details, and the full list of known quirks.