ginnoir/homelabstack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
72c565c3973b3632bcd815c89c7c2ea123cde2c3
homelabstack/AGENTS.md
T
ginnoirandClaude Sonnet 4.6 a44adc4814 docs: document gitea-first homelab deploys 
Switch CLAUDE.md and AGENTS.md to Gitea-primary language. Remove
github-runner from the management plane now that Gitea Actions handles
Caddy reloads and famapp builds. Disable GitHub deploy workflow.
Update apply-compose.ps1 status text.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-15 00:38:15 -05:00

2.4 KiB
Raw 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 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 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