# 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` |