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,75 @@
|
||||
# Application Design Plan — atheos-blog-lxc
|
||||
|
||||
**Stage**: INCEPTION — Application Design (**minimal depth**)
|
||||
**Date**: 2026-09-29
|
||||
|
||||
## Rationale for minimal depth
|
||||
|
||||
There is no application code to design — this project provisions a guest and installs an existing
|
||||
PHP application. "Application Design" here means recording the **runtime component map and its
|
||||
interfaces**, so that (a) the unit boundaries are defensible and (b) a later agent inheriting the
|
||||
repo can see how the pieces talk to each other without re-deriving it.
|
||||
|
||||
## Plan (checkboxes)
|
||||
|
||||
- [ ] Generate `components.md` — component definitions + responsibilities
|
||||
- [ ] Generate `component-methods.md` — the *interfaces* between components (not business logic)
|
||||
- [ ] Generate `services.md` — orchestration / request flow
|
||||
- [ ] Generate `component-dependency.md` — dependency matrix + data flow
|
||||
- [ ] Generate `application-design.md` — consolidated design
|
||||
- [ ] Validate design completeness and consistency
|
||||
|
||||
## Design questions
|
||||
|
||||
Most design decisions were already fixed in requirements.md. Below is the one that is genuinely
|
||||
open, plus two where I state my decision so you can veto it rather than having to choose blind.
|
||||
|
||||
---
|
||||
|
||||
### Q1 (genuine — blocks U4) — what git committer identity should Atheos use?
|
||||
|
||||
Atheos's git integration commits as a configured user. You told me you'll own the `armistace`
|
||||
credentials (**FR-11** — I must not create them). But `git` will refuse to commit at all without
|
||||
*some* identity, so leaving it entirely unset risks a broken first commit for you.
|
||||
|
||||
- **A)** Set a **neutral non-armistace** identity, e.g. `Atheos <atheos@atheos.local>`, purely so
|
||||
commits don't hard-fail; **you** override it with your own identity when you set up credentials.
|
||||
*(Recommended — leaves the tool working without impersonating you.)*
|
||||
- **B)** Set **nothing at all** — leave `user.name`/`user.email` unset, and the RUNBOOK tells you to
|
||||
set them as your first action after SSH-ing in. *(Purest reading of FR-11; first commit fails until you do.)*
|
||||
- **C)** Use a **placeholder under your name** (e.g. `armistace <ar17787@gmail.com>`) so commits are
|
||||
attributed to you out of the box. *(Note: this creates an armistace identity, which is what FR-11
|
||||
says I should not do — only pick this if you want to override that.)*
|
||||
- **X)** Other (describe after the tag)
|
||||
|
||||
`[Answer]:`
|
||||
|
||||
---
|
||||
|
||||
### Q2 (decision stated — veto if wrong) — pin Atheos to a specific upstream commit
|
||||
|
||||
Upstream Atheos is an actively-moving master branch with no releases. For a reproducible
|
||||
re-provision (FR-9), I propose pinning to a **specific verified commit SHA** resolved at build
|
||||
time and recorded in the script + RUNBOOK, rather than tracking `master`.
|
||||
|
||||
`[Answer]:` *(leave blank to accept)*
|
||||
|
||||
---
|
||||
|
||||
### Q3 (decision stated — veto if wrong) — where things live
|
||||
|
||||
- Web root: `/var/www/atheos` (Atheos app)
|
||||
- Atheos workspace: `/var/www/atheos/workspace` → this is where `blog` is cloned
|
||||
- nginx listens on **:80**, `root /var/www/atheos`, `index index.php`
|
||||
- php-fpm via **unix socket** (`/run/php-fpm83/...`) — not a TCP port, so nothing extra listens on the LAN
|
||||
|
||||
`[Answer]:` *(leave blank to accept)*
|
||||
|
||||
---
|
||||
|
||||
## Assumptions carried
|
||||
|
||||
- Atheos is served at the **site root** (`http://<ip>/`), not a subdirectory.
|
||||
- The operator completes Atheos's first-run installer in the browser (creates the admin user);
|
||||
the agent seeds neither the admin nor any Atheos user.
|
||||
- `blog` is pre-cloned into `workspace/` so it appears as a ready-to-open project (your Q6).
|
||||
@@ -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
|
||||
@@ -0,0 +1,32 @@
|
||||
# Unit of Work Plan — atheos-blog-lxc
|
||||
|
||||
**Stage**: INCEPTION — Units Generation (Part 1: Planning)
|
||||
**Date**: 2026-09-29 · **Depth**: minimal
|
||||
|
||||
## Rationale
|
||||
|
||||
The unit boundaries were already surfaced in the approved execution plan and the operator approved
|
||||
them ("continue looks good"). The decomposition is not genuinely in question — it follows the
|
||||
component dependency chain directly. So this plan carries **no open questions**; asking any would be
|
||||
ceremony. It is recorded here so the generation step is traceable rather than improvised.
|
||||
|
||||
## Decomposition principle
|
||||
|
||||
Units follow the **topological order of the dependency graph** — each unit ends in a state you can
|
||||
verify, and no unit depends on a later one. This matters because a failure in U3 (the genuinely
|
||||
uncertain one, Atheos-on-Alpine) must not leave U1/U2 work wasted or unverifiable.
|
||||
|
||||
## Plan
|
||||
|
||||
- [ ] Generate `unit-of-work.md` — unit definitions + responsibilities
|
||||
- [ ] Generate `unit-of-work-dependency.md` — dependency matrix + build order
|
||||
- [ ] Generate `requirement-to-unit-map.md` — **substitutes `unit-of-work-story-map.md`** (stories were skipped); every FR/NFR/AC assigned to exactly one unit
|
||||
- [ ] Validate unit boundaries and dependencies
|
||||
- [ ] Verify no requirement is unassigned
|
||||
|
||||
## Approval
|
||||
|
||||
Units were presented in the approved execution plan; the operator's "continue looks good" covers
|
||||
this decomposition. No blocking questions.
|
||||
|
||||
`[Answer]:` *(leave blank — approval recorded from the execution-plan gate)*
|
||||
Reference in New Issue
Block a user