ginnoir/homelabstack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
homelabstack/AGENTS.md
T
ginnoirandClaude Opus 5 28455a6787 docs: correct valhalla OS in the remaining agent-facing docs 
Same fix as 317a424, applied to the files an agent actually reads before
touching the host: AGENTS.md and both copies of the homelab-ssh skill.
They all claimed a headless Ubuntu server; valhalla is EndeavourOS (Arch).

Also record two things that cost time this session: there is no apt/apt-get
on the host, and ginnoir has passwordless sudo (needed for anything writing
to root-owned paths like /config/caddy/Caddyfile).

Historical records under plans/ and docs/superpowers/plans/ are left alone
on purpose — they document what was true when the work was done.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-05 12:10:32 -05:00

2.4 KiB
Raw Permalink Blame History

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 EndeavourOS (Arch) server reachable at ssh ginnoir@valhalla — pacman, not apt. ~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 to Gitea → Portainer polls every 5 min and redeploys that stack. GitHub is a temporary mirror only.
    • Caddyfile → git push → Gitea Actions (.gitea/workflows/deploy-caddy.yml) copies it + reloads Caddy. Fallback: apply-compose.ps1 -Caddy.
    • portainer-compose.yml / vault.hcl → apply-compose.ps1 -Portainer (Portainer can't manage itself).
  • Portainer app stacks must have empty UI environment variables. All config comes from stack.env via env_file: stack.env. Run scripts/check-portainer-stack-env.ps1 before pushing.
  • famapp images build on Gitea Actions (v* tags) and push to registry.ginnoir.com/ginnoir/famapp.
  • 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.

Reference in New Issue View Git Blame Copy Permalink