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

5.5 KiB

Raw Blame History

atheos-blog-lxc

Provisioning for a browser-based code editor (Atheos) in an Alpine LXC, wired to Gitea, with the armistace/blog repository cloned and ready to edit.

Built with the AI-DLC workflow — the full process trail (requirements, design, units, decisions, audit log) lives in aidlc-docs/.

What this is

A small, single-purpose Proxmox container that puts an editor in your browser so you can write blog posts and commit them to Gitea — without VS Code, without a cloud IDE, and without a build toolchain.


Guest	Proxmox LXC 136 on node `scotty`
OS	Alpine 3.23.2 (unprivileged, OpenRC)
URL	`http://192.168.178.57/` — LAN only
Stack	nginx → php-fpm 8.3 (unix socket) → Atheos IDE
Sizes	2 vCPU · 1 GB RAM · 20 GB rootfs · `onboot=1`
Editor	Atheos — PHP, no database, real vim keybindings
Project	`armistace/blog` cloned to `/var/www/atheos/workspace/blog`
Git auth	per-repository deploy key (write-enabled)

What it deliberately is NOT

Not VS Code / code-server / Coder. Atheos is an independent, lightweight PHP editor.
Not a build environment. The blog is a Pelican site, but building/publishing happens in your existing pipeline. There is intentionally no Python, no pelican, no make here — the presence of Python would be a defect (verified by acceptance criterion AC-8).
Not internet-facing. No reverse proxy host, no DNS record, no port-forward is created.

Quick start

If you just want to use it:

Open http://192.168.178.57/ and complete the Atheos first-run installer.
ssh root@192.168.178.57, then set your git identity — see RUNBOOK.md STEP 1. Git will not let you commit until you do, and that is deliberate: the agent does not create your identity.
Add the deploy key to armistace/blog and switch the remote to SSH — RUNBOOK.md STEP 2 & 3.

👉 The full operational guide is RUNBOOK.md. Start at STEP 1.

Repo layout

.
├── README.md                     this file
├── RUNBOOK.md                    ← operational guide; START AT STEP 1
├── docs/
│   ├── security-notes.md         credential model + hardening TODOs if ever exposed
│   └── resiliency-notes.md       what a non-PoC deployment would need
├── files/
│   ├── atheos.conf               nginx vhost (install to /etc/nginx/http.d/atheos.conf)
│   └── ssh-config                ~atheos/.ssh/config (the gitea-blog alias)
├── scripts/
│   ├── provision.sh              rebuild the whole guest from scratch
│   └── update-atheos.sh          update Atheos to latest upstream + re-pin
└── aidlc-docs/                   AI-DLC process trail (requirements → design → units → audit)

Rebuilding from scratch

The guest holds nothing unique — the blog's source of truth is Gitea — so a rebuild is cheap:

# on scotty (192.168.178.69), as root
pct destroy 136
sh scripts/provision.sh

scripts/provision.sh is written to be re-runnable and reproduces the documented build exactly, including the pinned Atheos commit and its verified tarball checksum.

Design decisions worth knowing

#	Decision	Why
D1	No git identity is configured by the agent. You set it (RUNBOOK STEP 1).	You own the `armistace` identity; setting it programmatically would impersonate you and blur attribution (requirement FR-11).
D2	Atheos is pinned to a commit SHA, with `update-atheos.sh` to deliberately move it.	Atheos has no releases; a moving branch is not reproducible.
D3	nginx :80, web root `/var/www/atheos`, php-fpm over a unix socket.	Smallest network surface — nothing extra listens on the LAN.
D6	Per-repository deploy key, not a personal access token.	A Gitea PAT's scopes are route groups matched against your whole account, so a stolen token reaches every repo you can write. A deploy key reaches exactly one.

Full rationale, including the alternatives that were rejected and the verification behind them, is in aidlc-docs/design-artifacts/application-design.md and docs/security-notes.md.

Security at a glance

Git auth: deploy key scoped to armistace/blog, private key mode 600, owned by the php-fpm user.
The SSH alias uses IdentitiesOnly yes, so no other key is ever offered.
The web app runs as a dedicated unprivileged user (atheos), which also owns the workspace.
⚠️ Accepted risk: Atheos runs as a web app with shell-exec reach, so a compromise can use the deploy key to write blog. That is the intended floor (one repo, one branch) rather than the ceiling. Keep branch protection on blog's master.
If this is ever exposed to the wider web, work through docs/security-notes.md §2 first.

Provenance


Built	2026-09-29
AI-DLC stages executed	Workspace Detection, Requirements, Workflow Planning, Application Design, Units Generation, Infrastructure Design, Code Generation, Build & Test
Stages skipped (with rationale)	Reverse Engineering, User Stories, Functional Design, NFR Requirements, NFR Design — see `aidlc-docs/plans/execution-plan.md`
Atheos pin	`f90cd1806dbe0e25673a77e27390e8b1a240c3f6` (build 611), tarball sha256 `03ebcb1479b59f1898b5fa50808b181750b42211698f7f7b4042cf2514d78b20`

5.5 KiB Raw Blame History