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.6 KiB

Raw Blame History

Component Dependencies — atheos-blog-lxc

Stage: INCEPTION — Application Design (minimal depth)

Dependency matrix

Rows depend on columns. → = depends on, — = none.

	C1 LXC	C2 nginx	C3 php-fpm	C4 Atheos	C5 workspace	C6 git	C7 blog
C1 LXC	—	—	—	—	—	—	—
C2 nginx	✔	—	✔ (I-1)	—	—	—	—
C3 php-fpm	✔	—	—	—	✔ (I-2)	—	—
C4 Atheos	—	—	✔	—	✔	✔ (I-3)	—
C5 workspace	—	—	—	—	—	—	✔
C6 git	✔	—	—	—	—	—	—
C7 blog	—	—	—	—	✔	—	—

Reading it: nothing works before C1; nginx is useless without php-fpm; Atheos depends on three things simultaneously; the clone is a leaf.

Build / provisioning order (topological)

C1 LXC
 ├─► C2 nginx ──► (needs) C3 php-fpm ──► C4 Atheos ──► C5 workspace ──► C7 blog (clone)
 └─► C6 git ──────────────────────────────────────────────┘

Critical path: C1 → C2/C3 → C4 → C5 → C7
Parallelisable: nginx install and git install are independent

External dependencies (version-pinned at build time)

Dependency	Source	Pin strategy
Alpine rootfs	PVE template `alpine-3.23-default_20260116_amd64.tar.xz`	template filename is versioned
`nginx`, `php83*`, `git`	Alpine `main`/`community` repos	record installed versions in the RUNBOOK at build time
Atheos	`github.com/Atheos/Atheos` (master, no releases)	pin to a resolved commit SHA (design Q2); record it
`armistace/blog`	Gitea, branch `master`	clone `master`; note the commit for the record

Coupling risks (where the design is tight)

Coupling	Why it's tight	Mitigation
nginx ↔ php-fpm socket path	a string must match exactly; failure is a 502 with no other signal	resolve from the installed pool config, then assert both sides match
FPM user ↔ workspace ownership	a UID mismatch yields "dubious ownership" or unwritable dirs	set ownership once from the actual FPM user, verify by writing a file
template filename ↔ Alpine version	a wrong/renamed template fails `pct create`	confirm the exact filename with `pveam available` before creating
Atheos master ↔ PHP 8.3	upstream targets older PHP; 8.3 may warn	smoke-test the installer page and check the error log for PHP fatals

2.6 KiB Raw Blame History