hermes
1c7db911df
Adds the branch-based publishing model: the editor writes to a long-lived
`atheos-writer` branch, and merging into `master` stays in Gitea.
Six macros installed into Atheos's macro store (a copy is kept in
files/macros.db.php so a rebuild reproduces them), invoked by right-clicking
the `blog` folder:
1. Start/Join Writer Branch idempotent create-or-switch + push -u
2. Commit + Push Writer Branch identity guard -> add -A -> commit (only
if something is staged) -> push
3. DESTRUCTIVE: Reset Writer to Master fetch -> reset --hard origin/master ->
push --force-with-lease
4. Status + Recent Log read-only
5. Refresh Master (ff-only) pull master down, return to writer
6. Merge Master Into Writer Branch when master has moved ahead
Atheos has no terminal and codegit exposes no branch-switching, so macros are
the only way to run arbitrary git from the UI. Verified: codegit's `checkout`
action takes a FILE argument - it is per-file revert, not branch switching.
Identity handling: the commit macros deliberately do NOT hardcode an identity.
php-fpm runs with HOME=/home/atheos (verified), the same global gitconfig the
operator edits over SSH, so hardcoding `git -c user.name=...` would OVERRIDE the
operator's own identity. Instead macro 2 guards on an identity existing and fails
with an actionable message - which is what design decision D1 intends.
Verified by exercising each command through the web server as the php-fpm user:
- macro 1, 4, 5 return rc=0 with correct output
- macro 2's identity guard fires with the exact RUNBOOK STEP 1 message
- macro 3 was tested with real divergence: committed on the writer branch,
reset --hard to master, force-pushed; origin/atheos-writer then matched
origin/master exactly (0 ahead, 0 behind)
Security note recorded in the docs and README: this model only holds if branch
protection is enabled on armistace/blog's master. It is currently NOT enabled,
so the deploy key could force-push master directly - the operator needs to turn
it on (repo-owner action).
Also documents two hazards found while testing:
- macro 2's `git add -A` stages everything, and a subsequent `reset --hard`
deletes any untracked file that was staged. Keep scratch files outside
workspace/blog/.
- recovery procedure for a file lost that way (git fsck --lost-found ->
ls-tree -> cat-file), which was used to restore a file during testing.
128 lines
6.2 KiB
Markdown
128 lines
6.2 KiB
Markdown
# 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
|
|
│ └── writer-branch-workflow.md how writing/publishing works from the editor
|
|
├── files/
|
|
│ ├── atheos.conf nginx vhost (install to /etc/nginx/http.d/atheos.conf)
|
|
│ ├── ssh-config ~atheos/.ssh/config (the gitea-blog alias)
|
|
│ └── macros.db.php installed copy of the Atheos writer macros
|
|
├── 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
|
|
|
|
- **Writing happens on a branch, never on `master`.** The editor commits to a long-lived
|
|
`atheos-writer` branch and you merge via PR in Gitea — see
|
|
[`docs/writer-branch-workflow.md`](docs/writer-branch-workflow.md).
|
|
⚠️ This only holds if **branch protection is enabled on `armistace/blog`'s `master`** — without it
|
|
the deploy key could force-push master directly. Confirm with the `branch_protections` API call in
|
|
that document.
|
|
- 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` |
|