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:
@@ -0,0 +1,149 @@
|
||||
# Execution Plan — atheos-blog-lxc
|
||||
|
||||
**Stage**: INCEPTION — Workflow Planning
|
||||
**Date**: 2026-09-29
|
||||
**Deploy Target**: Proxmox LXC (Alpine 3.23) on node **scotty** (.69). No K3s flavour, no CI.
|
||||
|
||||
---
|
||||
|
||||
## Detailed Analysis Summary
|
||||
|
||||
### Change Impact Assessment
|
||||
- **User-facing changes**: Yes — a new web UI (Atheos) becomes reachable on the LAN.
|
||||
- **Structural changes**: Yes — one new Proxmox guest (VMID 136).
|
||||
- **Data model changes**: No — Atheos is database-less; it stores config in files.
|
||||
- **API changes**: No.
|
||||
- **NFR impact**: Low — a small single-purpose guest; NFRs already captured in requirements.md.
|
||||
- **Existing systems touched**: `scotty` gains a guest + a template download. `armistace/blog` is
|
||||
**read** (cloned) only — never pushed to by the agent.
|
||||
|
||||
### Risk Assessment
|
||||
- **Risk Level**: **Medium** — the steps are well understood, but Atheos-on-Alpine is under-documented
|
||||
(C-1) and the install has a browser-driven first-run step.
|
||||
- **Rollback Complexity**: **Easy** — `pct destroy 136` removes the guest; nothing else is mutated.
|
||||
- **Testing Complexity**: **Simple-to-Moderate** — all acceptance criteria are observable
|
||||
(served page, file on disk, git remote, survives reboot).
|
||||
|
||||
### Component Relationships
|
||||
- **Primary component**: LXC 136 on scotty.
|
||||
- **Internal**: nginx → php-fpm (unix socket) → Atheos PHP app → workspace/ filesystem.
|
||||
- **External (read-only)**: `git.aridgwayweb.com/armistace/blog` (public clone).
|
||||
- **Operator-owned**: SSH key, git identity, Atheos login — the agent creates none of these.
|
||||
|
||||
---
|
||||
|
||||
## Workflow Visualization
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["User Request"])
|
||||
subgraph INCEPTION["🔵 INCEPTION PHASE"]
|
||||
WD["Workspace Detection<br/><b>COMPLETED</b>"]
|
||||
RE["Reverse Engineering<br/><b>SKIPPED</b>"]
|
||||
RA["Requirements Analysis<br/><b>COMPLETED</b>"]
|
||||
US["User Stories<br/><b>SKIPPED</b>"]
|
||||
WP["Workflow Planning<br/><b>IN PROGRESS</b>"]
|
||||
AD["Application Design<br/><b>EXECUTE</b>"]
|
||||
UG["Units Generation<br/><b>EXECUTE</b>"]
|
||||
end
|
||||
subgraph CONSTRUCTION["🟢 CONSTRUCTION PHASE"]
|
||||
FD["Functional Design<br/><b>SKIP</b>"]
|
||||
NFRA["NFR Requirements<br/><b>SKIP</b>"]
|
||||
NFRD["NFR Design<br/><b>SKIP</b>"]
|
||||
ID["Infrastructure Design<br/><b>EXECUTE</b>"]
|
||||
CG["Code Generation<br/><b>EXECUTE</b>"]
|
||||
BT["Build and Test<br/><b>EXECUTE</b>"]
|
||||
end
|
||||
subgraph OPERATIONS["🟡 OPERATIONS PHASE"]
|
||||
OPS["Operations<br/><b>PLACEHOLDER</b>"]
|
||||
end
|
||||
Start --> WD --> RA --> WP --> AD --> UG --> ID --> CG --> BT --> End(["Complete"])
|
||||
style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style RA fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style WP fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style CG fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style BT fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style RE fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
|
||||
style US fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
|
||||
style FD fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
|
||||
style NFRA fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
|
||||
style NFRD fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
|
||||
style AD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
|
||||
style UG fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
|
||||
style ID fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
|
||||
style OPS fill:#FFF59D,stroke:#F9A825,stroke-width:2px,color:#000
|
||||
linkStyle default stroke:#333,stroke-width:2px
|
||||
```
|
||||
|
||||
*(Plain-text equivalent for Matrix: WD ✅ → RA ✅ → WP ✅ → AD ▶ → UG ▶ → ID ▶ → CG ▶ → BT ▶ → Done.
|
||||
Skipped: RE, US, FD, NFRA, NFRD.)*
|
||||
|
||||
---
|
||||
|
||||
## Phases to Execute
|
||||
|
||||
### 🔵 INCEPTION PHASE
|
||||
- [x] Workspace Detection — COMPLETED
|
||||
- [x] Reverse Engineering — **SKIP** (greenfield repo; the *estate* recon was folded into Workspace Detection and recorded in `aidlc-state.md` → Existing Estate Facts)
|
||||
- [x] Requirements Analysis — COMPLETED
|
||||
- [x] User Stories — **SKIP** (user-confirmed; single operator, no app code. A **requirement→unit map** substitutes for `unit-of-work-story-map.md`, per the skipped-stories rule)
|
||||
- [x] Workflow Planning — COMPLETED
|
||||
- [ ] **Application Design** — **EXECUTE (minimal depth)**
|
||||
- **Rationale**: there *are* distinct components with real interfaces (nginx ↔ php-fpm socket, Atheos ↔ workspace, git ↔ remote). Recording them at minimal depth gives the handoff a component map and drives unit boundaries. Minimal, not comprehensive — no app code exists to design.
|
||||
- [ ] **Units Generation** — **EXECUTE**
|
||||
- **Rationale**: genuinely multi-unit work (guest, web stack, app, VCS, docs) with an ordering dependency.
|
||||
|
||||
### 🟢 CONSTRUCTION PHASE
|
||||
- [ ] Functional Design — **SKIP**
|
||||
- **Rationale**: no business logic to design; the "functions" are package installs and config files already specified in requirements.md.
|
||||
- [ ] NFR Requirements — **SKIP**
|
||||
- **Rationale**: all NFRs already captured (requirements.md §3); nothing new surfaces at construction.
|
||||
- [ ] NFR Design — **SKIP**
|
||||
- **Rationale**: same — NFRs here are simple resource/reboot-survival constraints, not a design problem.
|
||||
- [ ] **Infrastructure Design** — **EXECUTE**
|
||||
- **Rationale**: **this is the real design work for an infra project** — the guest spec, storage choice, template provenance, network mode, resource sizing, and the OpenRC service wiring. Getting this wrong is the main risk (C-1/C-2/C-3).
|
||||
- [ ] **Code Generation** — EXECUTE (always)
|
||||
- **Rationale**: the provisioning script + the docs are the deliverables.
|
||||
- [ ] **Build and Test** — EXECUTE (always)
|
||||
- **Rationale**: here "build and test" = **apply against the live node and verify**, plus the reboot-survival cycle (AC-6). Not a compiled artifact.
|
||||
|
||||
### 🟡 OPERATIONS PHASE
|
||||
- [ ] Operations — PLACEHOLDER (future deployment/monitoring workflows)
|
||||
|
||||
---
|
||||
|
||||
## Unit Plan (provisional — finalised in Units Generation)
|
||||
|
||||
| Unit | Scope | Depends on | Primary ACs |
|
||||
|---|---|---|---|
|
||||
| **U1** | LXC creation: download Alpine 3.23 template on scotty, `pct create 136` (20 GB root, 2 vCPU, 1 GB, onboot, unprivileged), base config, timezone, package index | — | AC-1 |
|
||||
| **U2** | Web stack: `nginx` + `php83-fpm` + `php83-{session,zip,openssl,mbstring}`, `allow_url_fopen`, php-fpm pool, nginx vhost | U1 | AC-2 |
|
||||
| **U3** | Atheos install: fetch pinned upstream commit into the web root, correct ownership/permissions on `config.php`, `data/`, `workspace/`, `plugins/`, `themes/` | U2 | AC-2, AC-3 |
|
||||
| **U4** | Git + clone: install git, `safe.directory`, committer identity (non-armistace), clone `armistace/blog` into `workspace/`, leave remote HTTP | U1, U3 | AC-3, AC-4, AC-5 |
|
||||
| **U5** | Repo + docs: `README.md`, `RUNBOOK.md` (incl. SSH remote-switch + operator credential steps), `docs/security-notes.md`, `docs/resiliency-notes.md`, re-provision script | U1–U4 | AC-7 |
|
||||
|
||||
---
|
||||
|
||||
## Estimated Timeline
|
||||
|
||||
**No wall-clock estimate offered** — fabricating one would be worse than omitting it. The work is
|
||||
5 units, several of which are a handful of commands each; the only genuinely uncertain step is
|
||||
U3 (Atheos-on-Alpine, risk C-1). Each unit ends in a verifiable state, so progress is measurable
|
||||
even without a time estimate.
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- **Primary goal**: a LAN-reachable Atheos on Alpine where `armistace/blog` is cloned and editable,
|
||||
with credentials owned entirely by the operator.
|
||||
- **Key deliverables**: LXC 136 on scotty; Atheos served by nginx/PHP; the blog clone in the
|
||||
workspace; README + RUNBOOK + re-provision script; security/resiliency TODO notes.
|
||||
- **Quality gates**:
|
||||
- AC-1…AC-8 all demonstrated with real command output (not assertions)
|
||||
- Atheos served (not 502/404) — verified over HTTP from the LAN
|
||||
- **Reboot-survival verified** (AC-6), not assumed
|
||||
- **No Python/pelican present** (AC-8) — proves scope was respected
|
||||
- **No `armistace` credential or git identity created by the agent** (FR-11)
|
||||
- Independent review of the generated provisioning script before the Build-and-Test gate
|
||||
- `audit.md` complete and append-only; `aidlc-state.md` current
|
||||
Reference in New Issue
Block a user