hermes
a6fb61d0ea
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.
66 lines
2.8 KiB
Markdown
66 lines
2.8 KiB
Markdown
# 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.
|