32 lines
2.0 KiB
Markdown
32 lines
2.0 KiB
Markdown
# 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`](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 `scp`s 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.
|