Files

T

hermes a6fb61d0ea feat: provision Alpine LXC 136 running Atheos, wired to Gitea

Provisions a LAN-only browser code editor (Atheos) in an Alpine 3.23 LXC on the
scotty PVE node, with armistace/blog cloned and ready to edit. Built via the
AI-DLC workflow; the full process trail is in aidlc-docs/.

Deliverables
- scripts/provision.sh          rebuild the guest from scratch (re-runnable)
- scripts/update-atheos.sh      move Atheos to latest upstream and RE-PIN
- scripts/build-and-test.sh     captures evidence for every acceptance criterion
- files/atheos.conf             nginx vhost (socket path byte-matches the FPM pool)
- files/ssh-config              ~atheos/.ssh/config deploy-key alias
- RUNBOOK.md                    operational guide (START AT STEP 1)
- docs/security-notes.md        credential model + wider-web hardening TODOs
- docs/resiliency-notes.md      what a non-PoC deployment would need

Design decisions
- D1 no git identity is configured by the agent; the operator sets it. Git will
  refuse the first commit until then, which is deliberate (requirement FR-11).
- D2 Atheos pinned to commit f90cd18 (build 611) with a verified tarball sha256,
  plus update-atheos.sh as the deliberate escape hatch.
- D3 nginx :80, web root /var/www/atheos, php-fpm over a unix socket.
- D6 git auth is a per-repository DEPLOY KEY scoped to armistace/blog, not a
  personal access token (a PAT's write:repository scope reaches every repo the
  account can write).

Verified on the live guest (40 checks, 0 failures)
- AC-2  Atheos served over HTTP 200 by nginx+php-fpm; socket paths byte-match
- AC-3  20 posts + themes/cleanblog present; owned by the php-fpm user
- AC-4  all five writable paths writable as the service user
- AC-5  remote targets armistace/blog; deploy key authenticates over SSH
- AC-6  survival proven with a real container restart, marker byte-identical
- AC-8  no python/pelican/pip/make and no DB engine - scope boundary enforced
- FR-11 git identity is empty; deploy key mode 600 owned by the service user

Traps documented in the RUNBOOK (each cost real debugging time)
- The Gitea SSH user is `gitea`, NOT `git` (app.ini SSH_USER=gitea). With `git`,
  sshd answers "Invalid user git" and rejects before reading authorized_keys,
  which is indistinguishable from a bad key.
- The Gitea SSH endpoint is the LAN address (:22 is not forwarded publicly).
- `uptime` and `free` report the PVE HOST inside an LXC without lxcfs, so a
  container that just restarted can claim days of uptime.

2026-09-29 15:50:34 +10:00

2.4 KiB

Raw Blame History

Services / Request Flow — atheos-blog-lxc

Stage: INCEPTION — Application Design (minimal depth)

There is no service layer to design (no application code). What matters is the two flows the guest supports, and where each can break.

Flow 1 — Operator edits and commits

Browser (LAN)
   │  http://<lxc-ip>/
   ▼
nginx (C2, :80)
   │  location ~ \.php$  →  fastcgi_pass unix:<FPM_SOCKET>     [I-1]
   ▼
php-fpm (C3, php83)
   │  executes as the FPM user
   ▼
Atheos (C4, /var/www/atheos)
   ├── reads/writes  workspace/blog/**            [I-2 write contract]
   └── on Commit:  git (C6)
                     │  safe.directory must include workspace/  [I-3]
                     │  identity UNSET by design (Q1=B)
                     ▼
                commit created in the local clone

Break points: FPM socket mismatch (502) · unwritable workspace/ (installer/editor errors) · dubious-ownership (git refuses) · missing identity (commit refused until operator sets it).

Flow 2 — Operator pushes (operator-owned path)

Atheos Commit  →  operator adds SSH key + sets git identity  →  remote switched to SSH (operator)
                                                                      │
                                                                      ▼
                                                            Gitea (C8) receives the push

The agent builds the path but does not walk it: it clones over HTTPS, leaves the remote as-is, and documents the switch. Pushing is the operator's first hands-on act.

Flow 3 — Build/publish (OUT OF SCOPE — happens elsewhere)

Gitea (C8)  →  existing pipeline (NOT on this guest)  →  make html  →  published site

Explicitly excluded (Q1=A). No Python, no pelican, no make on this guest. If this flow were expected here, C-1's risk profile would change materially — it is not.

Provisioning order (what must exist before what)

U1 guest  →  U2 nginx+php-fpm  →  U3 Atheos  →  U4 git + clone  →  U5 docs + script
                                                                    ▲
                       U4 also depends on U1 (git) ─────────────────┘

Each arrow is a real dependency: installing Atheos before php-fpm leaves nothing to serve it; cloning before Atheos exists has no workspace to clone into.

2.4 KiB Raw Blame History