atheos-blog-lxc/aidlc-docs/design-artifacts/application-design.md

Application Design (consolidated) — atheos-blog-lxc

Stage: INCEPTION — Application Design (minimal depth) · Date: 2026-09-29 Deploy target: Proxmox LXC 136 on node scotty (.69) — Alpine 3.23 · LAN-only

---

1. What this system is

A small, single-purpose guest whose only job is to put a browser editor in front of the armistace/blog working copy. It is deliberately not a build environment.

                    ┌───────────────────────── LXC 136 (scotty) ─────────────────────────┐
   Browser (LAN)    │                                                                    │
   http://<ip>/ ────┼──► nginx :80 ──unix socket──► php-fpm (php83) ──► Atheos (PHP)     │
                    │                                        │                           │
                    │                                        ├──► workspace/blog/**  (rw) │
                    │                                        └──► git CLI ──► local commit│
                    └────────────────────────────────────────────────────────────────────┘
                                                                     │
                                            (operator, later) SSH identity + SSH remote
                                                                     ▼
                                                       Gitea  git.aridgwayweb.com

2. Components

ID	Component	Role
C1	LXC 136 on scotty, Alpine 3.23	isolated runtime, OpenRC, 20 GB root, onboot
C2	nginx :80	HTTP front end; sends *.php to C3
C3	php-fpm php83	PHP runtime; ZIP/OPENSSL/MBSTRING; allow_url_fopen=On
C4	Atheos (pinned SHA)	the editor; git via its codegit component
C5	/var/www/atheos/workspace	project storage (writable)
C6	git CLI	VCS; safe.directory set; no identity (operator-owned)
C7	blog working copy	clone of armistace/blog on master
C8	Gitea (external)	clone source; agent never pushes
C9	Operator (external)	owns SSH key, git identity, Atheos admin, remote switch

3. Key interfaces

1. nginx → php-fpm: fastcgi_pass unix:<FPM_SOCKET> must equal the pool's listen =. Mismatch ⇒ 502.
2. Atheos → filesystem: writable config.php, data/, workspace/, plugins/, themes/. Failure ⇒ installer dependency error.
3. Atheos → git: needs git on PATH and safe.directory for the workspace (else dubious ownership). Identity intentionally unset.
4. git → Gitea: HTTPS clone (public); operator later switches to SSH.
5. OpenRC: nginx + php-fpm83 enabled at default runlevel — otherwise first reboot breaks service (AC-6).

4. Design decisions (from the gate)

#	Decision	Source
D1	No git identity configured by the agent. user.name/user.email left unset; RUNBOOK instructs the operator to set them first.	Q1=B
D2	Atheos pinned to a resolved commit SHA, with an additional update script that re-clones at latest and re-pins.	Q2
D3	Web root /var/www/atheos; workspace /var/www/atheos/workspace; nginx :80; php-fpm via unix socket.	Q3
D4	Atheos served at the site root.	assumed, accepted
D5	Operator completes Atheos's first-run installer; agent seeds no users.	FR-11 / Q2 of requirements
D6	Credential = a per-repository Gitea deploy key scoped to armistace/blog, write-enabled (read_only:false), owned by the php-fpm user, aliased via ~/.ssh/config with IdentitiesOnly yes. Not a PAT (account-wide scopes) and not a dedicated Gitea user (no blast-radius reduction for blog). Private key generated on the guest; public half handed to the operator to add in-repo.	Andrew, 2026-09-29 (security review)

5. Scope guards (each is a testable negative)

• No database installed
• No Python / pelican / make — the presence of Python is a defect (AC-8)
• No NPM proxy host / DNS / port-forward (FR-10)
• No armistace credential, SSH key, or git identity created by the agent (FR-11)

6. Design-level risks handed to Infrastructure Design

• C-1 Atheos on Alpine is under-documented → resolve the FPM socket and extension package names from the installed system, not from upstream docs.
• C-2 OpenRC, not systemd → all service work uses rc-service / rc-update.
• C-3 Alpine template must be downloaded on scotty first (pveam update + download).
• C-4 The installer needs a writable web root before it will run.

7. Unit mapping

U1 guest (C1) · U2 web stack (C2,C3) · U3 Atheos (C4,C5) · U4 git + clone (C6,C7) · U5 docs + script (all)