Files

T

hermes c2897ed660 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:44:11 +10:00

2.8 KiB

Raw Blame History

Component Methods / Interfaces — atheos-blog-lxc

Stage: INCEPTION — Application Design (minimal depth) Note: No business logic exists to specify. These are the contracts between components — the things that must match or the stack silently fails (the classic 502 / permission-denied class).

I-1 · nginx → php-fpm (the interface most likely to break)

nginx server block:
  listen 80;
  root /var/www/atheos;
  index index.php index.html;

  location = /index.php { fastcgi_pass unix:<FPM_SOCKET>; ... }
  location ~ \.php$    { fastcgi_pass unix:<FPM_SOCKET>; ... }

Contract: <FPM_SOCKET> in nginx.conf must equal the listen = path in the php-fpm pool. Alpine's php83-fpm default differs between packages — resolve it from the installed /etc/php83/php-fpm.d/www.conf rather than assuming.

Input: HTTP request; Output: text/html from the PHP process
Failure mode if mismatched: 502 Bad Gateway (socket missing) — AC-2 fails

I-2 · Atheos → filesystem (the write contract)

Atheos's installer requires write access to exactly these paths, relative to /var/www/atheos:

Path	Why	Mode
`config.php`	installer writes the config; file must exist	writable by FPM user
`data/`	user accounts, settings	writable
`workspace/`	projects (incl. the `blog` clone)	writable
`plugins/`	plugin install/marketplace	writable
`themes/`	theme install	writable

Owner/group: the php-fpm run user (resolved from the pool config)
Failure mode: installer shows a dependency error; AC-3 fails

I-3 · Atheos (`codegit`) → git CLI

Requires: git on PATH
Requires: safe.directory for the workspace — otherwise git refuses with detected dubious ownership because the FPM user differs from the filesystem owner
Identity: user.name / user.email are deliberately UNSET (design Q1=B). The operator sets them first thing after SSH (see RUNBOOK).
Failure mode: "dubious ownership" errors, or commit refused for missing identity

I-4 · git CLI → Gitea

Remote (initial): https://git.aridgwayweb.com/armistace/blog.git (public ⇒ no credential)
Remote (operator, later): git@git.aridgwayweb.com:armistace/blog.git — the RUNBOOK gives the exact git remote set-url command for after the key is added
Contract: the agent must not alter the remote to SSH itself (FR-6/FR-11)

I-5 · OpenRC service contract (not systemd)

Service	Enable	Purpose
`nginx`	`rc-update add nginx default`	HTTP
`php-fpm83`	`rc-update add php-fpm83 default`	FastCGI (verify exact rc name on 3.23)

Failure mode if not enabled: works until first reboot, then AC-6 fails. This is why NFR-2 is verified with an actual reboot rather than a service-status check.

2.8 KiB Raw Blame History