ginnoirandClaude Opus 5
28455a6787
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>
34 lines
2.4 KiB
Markdown
34 lines
2.4 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
|
|
**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.
|