hermes/atheos-blog-lxc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: provision Alpine LXC 136 running Atheos, wired to Gitea

Browse Source 
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.
This commit is contained in:
hermes
2026-09-29 15:44:11 +10:00
commit c2897ed660
26 changed files with 2333 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+119
View File
@@ -0,0 +1,119 @@
# 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/`](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](https://github.com/Atheos/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:**
1. Open **http://192.168.178.57/** and complete the Atheos first-run installer.
2. `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.
3. 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](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:
```sh
# 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`](aidlc-docs/design-artifacts/application-design.md)
and [`docs/security-notes.md`](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` |