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.
This commit is contained in:
@@ -1,3 +1,119 @@
|
||||
# atheos-blog-lxc
|
||||
|
||||
Alpine LXC running Atheos (browser editor) wired to Gitea + armistace/blog. LAN-only. Built with AI-DLC.
|
||||
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` |
|
||||
|
||||
Reference in New Issue
Block a user