From 9a7962660577d3bdcd54b6e3e5416d6e87dee8dd Mon Sep 17 00:00:00 2001 From: Garrett Allen <98648590+Gerrrt@users.noreply.github.com> Date: Wed, 26 Aug 2026 14:41:53 +0000 Subject: [PATCH] ADR-0011: keep the wiki internal, put the emergency tier on paper MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Lemmiwinks wiki runs on Oracle at 10.0.99.30, behind the same firewall, switch and power as everything it documents. Three ordinary failures take the documentation out along with the thing it documents, and the audience makes that sharper than it would otherwise be: these pages are written for a non-technical household, for the case where I am unreachable. A recovery document that requires the estate to be healthy is a reference manual that has been mislabelled. ADR-0008 makes external exposure look like the obvious fix, since Caddy and step-ca are already on Winterfell and reusing them would be cheap. That is the option this ADR declines, and it is the one worth writing down. Publishing the wiki that way would make it depend on a reverse proxy and a CA that run in this house, on the same rack and the same power, so every failure that makes the docs unreachable today still would — plus two more components able to cause the same outage alone. An expired internal certificate is the obvious one: it fails quietly and looks like a browser problem to whoever is holding the phone. Also rejected: making the repo public, which buys convenience and publishes the addressing plan, rack order and the host holding the password manager; and a periodic offline export, which is the only option both family-readable and independent of the house, but decays without announcing it. A stale copy read with confidence during an emergency is worse than no copy. So: three tiers, each depending on strictly less than the one above. Paper for the emergency subset, the wiki for everything, GitHub for the technical second named on the card. The consequences section is where the cost is. Paper goes stale as silently as an export would — the difference is that its staleness is bounded by a deliberate annual drill, which makes that drill load-bearing rather than tidy. The rack's physical order is now part of a document that cannot be hot-fixed. And the GitHub grant presents as working right up until it matters, so it wants testing once. Refs Gerrrt/Lemmiwinks#3 Co-Authored-By: Claude Opus 5 --- README.md | 2 +- docs/adr/0011-keep-the-wiki-internal.md | 117 ++++++++++++++++++++++++ 2 files changed, 118 insertions(+), 1 deletion(-) create mode 100644 docs/adr/0011-keep-the-wiki-internal.md diff --git a/README.md b/README.md index 58239eb..ff74c36 100644 --- a/README.md +++ b/README.md @@ -155,7 +155,7 @@ rack; a dashed border means egress only. Full topology and data flow in ├── docs/ │ ├── architecture.md network.md hardware.md │ ├── observability.md security.md roadmap.md -│ ├── adr/ # 10 architecture decision records +│ ├── adr/ # 11 architecture decision records │ └── runbooks/ # deploy, add device, rotate creds, certs, key backup, │ # purge, restore the firewall, ship firewall logs, │ # enable suricata diff --git a/docs/adr/0011-keep-the-wiki-internal.md b/docs/adr/0011-keep-the-wiki-internal.md new file mode 100644 index 0000000..9d6360a --- /dev/null +++ b/docs/adr/0011-keep-the-wiki-internal.md @@ -0,0 +1,117 @@ +# ADR-0011: Keep the wiki internal and put the emergency tier on paper + +**Status:** Accepted · 2026-08 + +## Context + +The Lemmiwinks wiki documents this estate, and it runs inside it — a container +on Oracle at `10.0.99.30`, on VLAN 99, behind the same firewall, switch and +power as everything it describes. The consequence is circular in a way that is +easy to state and easy to leave unfixed: **the instructions for recovering a +system are hosted on that system.** + +Three ordinary failures take the documentation out along with the thing it +documents. pfSense down: no docs. Oracle down: no docs. Power cut: no docs. The +household runbook makes the shape of it obvious — its Step 5 tells the reader to +browse to `https://10.0.99.1`, and that instruction is itself only readable over +the network whose gateway is at `10.0.99.1`. + +The audience makes this sharper than it would otherwise be. These pages are +written for a non-technical household, for the case where the person who built +the estate is unreachable. A recovery document that requires the estate to be +healthy is not a recovery document; it is a reference manual that has been +mislabelled. + +The content itself is not at risk. The wiki syncs from a GitHub repository, so +the words survive any hardware failure here. But surviving and being *reachable +by the intended reader* are different properties, and only the first was ever +true. The repository is private, it is a tree of raw Markdown with no navigation, +and nothing anywhere told anyone it existed. + +ADR-0008 makes external exposure look like the obvious fix. It already placed +Caddy and step-ca on the Winterfell mini PC for the sensitive tier, so the +machinery for publishing a service exists and reusing it would be cheap. + +## Decision + +**The wiki is not exposed outside the estate.** No port forward, no external +hostname, no reverse-proxy entry. It stays reachable only from inside, exactly +as it is today. + +Instead the documentation is treated as three tiers, each depending on strictly +less than the one above it, and each covering strictly less: + +| Tier | Contents | Dependencies | +| --- | --- | --- | +| Printed break-glass card | Who to call, reset order, where credentials are | None | +| The wiki | Everything | The estate's network and power | +| The GitHub repository | The same words, as raw Markdown | Internet, plus a private-repo grant | + +**The emergency subset lives on paper**, as a one-page card kept on the fridge +and with the estate paperwork. That work is done; this ADR records why it is the +top tier rather than a stopgap. + +**The GitHub copy is documented as a technical recovery path and not as a +household one.** Read access is granted to the person named on the card as the +technical second — someone who knows what a repository is — and that grant is +tested once rather than assumed. + +Three alternatives were considered and rejected. + +**Publish the wiki behind Caddy and step-ca**, per the ADR-0008 pattern. This is +the one that looks right and is not. It would make the documentation depend on a +reverse proxy and a certificate authority that both run in this house, on the +same rack and the same power as the wiki itself. The failure modes that make the +docs unreachable today would still make them unreachable, and there would be two +more components able to cause the same outage on their own — an expired internal +certificate being the obvious one, since it fails quietly and looks like a +browser problem to whoever is holding the phone. It would add exposure and +availability risk in exchange for availability that does not materialise in any +of the three cases that motivated it. + +**Make the Lemmiwinks repository public**, so no account is needed. This buys +real convenience, and it publishes the estate's full topology: addressing plan, +VLAN layout, rack order, service inventory, and the specific host that holds the +password manager. That is a poor trade for a fallback whose realistic reader is +one named person. + +**Keep a periodic offline export** — a PDF or synced folder on family phones. +Attractive, because it is the only option that is both readable by the household +and independent of the house. Rejected because it decays without announcing it: +it requires a recurring manual export, nothing detects the day it stops, and a +stale copy read with confidence during an emergency is worse than no copy at +all. The paper card covers the same need with a maintenance obligation that is +visible on its face and checked annually. + +## Consequences + +- **The emergency tier is now a maintenance obligation rather than a solved + problem, and that is the honest cost.** A printed card goes stale silently in + exactly the way an offline export would; the difference is that its staleness + is bounded by a deliberate annual drill and by a `Last checked` line on the + card itself. If that drill does not happen, this decision quietly degrades to + "the household has nothing", and the drill is therefore load-bearing rather + than tidy. +- **The rack's physical order becomes part of the documentation contract.** The + card instructs whoever holds it to press the power button on the fifth box + from the top. Reordering the rack invalidates a document that cannot be + hot-fixed, and someone will follow it anyway. This is already noted in the + wiki's physical-topology page; it is a consequence of choosing paper. +- **The GitHub tier depends on an access grant that must actually be tested.** + Granting and never verifying is the standard failure here, and it presents as + working right up until the moment it matters. +- **The wiki should be described as a convenience rather than a recovery tool, + and written that way.** Anything that positions it as the thing to consult in + an emergency is relying on a component this decision lets fail. The same + distinction ADR-0010 draws for DNS filtering applies here. +- **Nothing about the estate's exposure changes.** No new inbound path, no new + certificate to renew, no new service on the Winterfell segment whose dilution + ADR-0008 already conceded. Declining to add one is a small repayment against + that cost. +- **Reversing this is cheap if the premise changes.** The rejection of external + exposure rests on emergency-time availability, not on secrecy. If the wiki + ever needs to be readable from outside for an ordinary reason — reading it at + work, or a second household — that is a different question with a different + answer, and it should supersede this ADR rather than be argued as an exception + to it. The paper tier stays regardless; it is not what external exposure would + replace.