Architecture Decision Records
Significant decisions in TAPPaaS are made in writing, before the code: each one is an Architecture Decision Record (ADR) in this directory, and it stays here forever — superseded ADRs are marked, never deleted. If you want to know why the platform is the way it is, this is the trail.
The Status column tracks each decision's lifecycle — Draft → Proposed → Accepted → Superseded (ADR-013 §2); Accepted — implemented means the code is live.
The 2.0 spine — the taxonomy family
| ADR | Status | Decides |
|---|---|---|
| ADR-007 — TAPPaaS Taxonomy | Accepted — implemented | The model everything hangs on: one Site, three classification domains (People · Apps · Environments), Health as a cross-cutting lens. Detailed per domain in sub-ADRs 007a–007e (007e partial), realization (managers/controllers) in 007f. |
| ADR-009 — Composition Meta-Model | Proposed | How a deployable unit is built (module = atomic deployable unit; <module>:<service> coordinates) — composition, as distinct from ADR-007's classification. |
| ADR-007a — People | Accepted — implemented | Who uses the platform: Organization → Group → User plus a cross-cutting Role, owned by people-manager and realized in Authentik. |
| ADR-007b — Apps | Accepted — implemented | The Module rib of the taxonomy: what a module's config declares and where it lives. |
| ADR-007c — Environments | Accepted — implemented | Where apps run: an Environment's zones, domain, update window and security posture, owned by exactly one Organization — except mgmt, the Site's control-plane Environment. |
| ADR-007d — Site | Accepted — implemented | site.json — the Site's own state: nodes, repositories, schedule, default environment. |
| ADR-007e — Health | Accepted — partially implemented (status-badge UI is future) | Health as a cross-cutting lens, and the site notification target. |
| ADR-007f — Realization | Accepted — implemented | Manager → Controller → Service: how the control plane is built, and the Stack-promotion rule. |
The workload ontology — ADR-022 family
The vocabulary every other ADR now borrows: what a module is, where it sits, who manages it.
GLOSSARY.md at the repository root is the consolidated SSOT for these terms.
| ADR | Status | Decides |
|---|---|---|
| ADR-022 — Workload Ontology | Accepted | The umbrella: why the ontology exists and how the ribs fit together. |
| ADR-022a — Administrative Domain | Accepted | The boundary of one administrative authority — what external is measured against. The relationship taxonomy (D6/D7) is parked for 2.1. |
| ADR-022b — Location | Accepted | Where something physically is: Site ⊃ Building ⊃ Room ⊃ Rack. Facility removed. |
| ADR-022c — Node and Host | Accepted | Node returns to its ArchiMate meaning; adds cluster member and Host; namespaces tier. |
| ADR-022d — Workload Classification | Accepted | kind — what type of thing a module is, and why it is a dispatch key. |
| ADR-022e — Module Scope | Accepted | module.tier becomes scope: site | environment. Scope is not stack, not multiplicity, not a layer. |
| ADR-022f — Kind Values and OS | Accepted — folded into ADR-022d | The kind leaves: vm, lxc, machine (was host), application (was app), device — plus the OS facet. |
| ADR-022g — Management | Accepted | management: managed | unmanaged; external means only "outside the Administrative Domain". |
| ADR-022h — Facet Register | Accepted | Which attributes are facets beside the single-valued kind, and the gate a new one must pass. |
Platform decisions
| ADR | Status | Decides |
|---|---|---|
| ADR-001 — Trunk-mode VLAN connectivity | Superseded (not adopted) | VMs attach on trunk ports; zones are VLANs. |
| ADR-002 — Dynamic VLAN configuration | Superseded | Zone/VLAN wiring happens at deploy time, driven by module config. |
| ADR-003 — Dependency management | Accepted — implemented | Modules declare dependsOn; install order is derived, never hardcoded. |
| ADR-004 — Module catalog & config cascade | Accepted — L2 live; L1/L3 superseded by ADR-007 | Where module configuration comes from and how overrides cascade. |
| ADR-005 — Variant domain architecture | Superseded → ADR-007c | Per-client variants of the platform (variants → environments). |
| ADR-006 — Identity: users and roles | Accepted — SSO live; people model → ADR-007a | The identity model behind SSO (Authentik) — users, groups, roles. |
| ADR-008 — Switch module / network infrastructure | Partially implemented (as network-manager) |
Physical switches and APs become managed parts of the platform. |
| ADR-010 — VPS satellite | Accepted — implemented (Debian variant) | The optional off-premises satellite: public ingress, off-site backup, admin VPN. |
| ADR-012 — Backup enhancement | Accepted (v1.0) — v1.0 additions not built yet | Where PBS lives (install-resolved placement, or an external PBS consumed by URL), what a module asks to have backed up (backup:vm / backup:filesystem), and how often (site → environment → module cascade). |
| ADR-014 — Zone and Environment Lifecycle | Accepted — implemented | Creating, binding, enabling/disabling and retiring zones and environments through managers, not hand-edited zones.json. |
| ADR-016 — Source NAT for subnet-filtering devices | Accepted — implemented | Masquerade into a zone for IoT appliances that only accept sessions from their own subnet: zone-owned snat-allowed-from gate, module-local snat.json, network-manager snat verbs. |
| ADR-017 — Update scheduling and mothership self-update | Accepted | When the sweep runs and how the mothership updates itself (systemd ExecStartPre=+, schedule from site.json). D9: memory in the run — growth that does not fit is held, suspended modules are patched, pauseOk modules may be paused for room in the maintenance window. |
| ADR-018 — SSH Identity Resolution Under Sudo | Superseded in part | Why the manager estate runs as tappaas, not root; the per-call-site -i sweep is superseded by the #533 ownership guard. |
| ADR-019 — HA and Cross-Node VM Migration Policy | Accepted — implemented (v1.1) | The full migrate-vm.sh matrix — HA/non-HA, live-vs-offline by CPU compatibility (--force for downtime), strict/comment round-trip, when module.json.node is rewritten. v1.1 adds node uplink redundancy (bonded LACP uplinks, #40). |
| ADR-020 — Declared-Field Change Model | Accepted — implemented | Unifies validate · drift · modify behind one desired-state resolver, one differ and one change-class taxonomy (immutable / in-place / grow-only / migrate / …); each <provider>:<service> declares how to change — or refuse — the fields it owns, in services/<svc>/fields.json. modify --set field=value is the sanctioned path (#498/#557), with a static pre-gate for what cannot change in place and a disruption gate (--force / rebootOk) decoupled from update-tappaas --force. network-manager modify <zone> --set is the second manager (#538). D11: a verb may also offer shortcut options, one field each, that expand into --set (site, location, environment and identity modify). ADR-019 plugs into the update-node.sh hook. How it is built: ADR-020 realization. |
| ADR-021 — Split-Horizon DNS and Service Reachability | Accepted — implemented | The internal answer for a published name is always the DMZ gateway, for every zone: DNS says "go to Caddy", Caddy + Authentik decide who gets in. Authorization moves out of the address (which caused the drift) and into identity. One resolver for all three writers (network-manager split-horizon-target, D5), ending the drift where three code paths resolved the answer from different zones (#577). Reaching Caddy is a host-scoped firewall rule — the DMZ gateway /32 on tcp/80+443 (D3) — and no zone may hold dmz in access-to (D3b, invariant I5): that grant reached the whole DMZ subnet including the firewall's own GUI and SSH (#618). A wildcard cert no longer implies a wildcard record (D4), and a name with no public DNS degrades cleanly instead of failing (R3). |
| ADR-023 — Reverse Proxy Access Rules | Accepted — implemented | What Caddy lets through once a caller reaches it. Every route — the primary and each proxyRoutes entry — has its own default proxyAllowedZones plus optional proxyAccess path exceptions, so a module can publish one webhook path without publishing the whole app (#642, #643 merged). Unlisted paths fall back to the route's own access list; none denies all. Access lists sit on every handle, never on the domain, because Caddy tries path handles first. |
| ADR-025 — Config migrations and the upgrade path | Accepted | How a release brings a site's config/ forward, and what a release may assume about where a site is upgrading from. Ordered, idempotent migrations/NNNN-<slug>.sh run by tappaas-self-prepare.sh — before the rebuild and before any module, which pre-update.sh cannot be (D2) — each with --check, a backup under config/.migrations/backup/NNNN/ and a ledger entry in config/.migrations/applied (#545 backs both up). A failed migration stops the run before anything is updated and is notified through #651. The review rule: a change that renames or re-schemas anything under config/ ships with its migration and a before→after fixture test in the fast tier. No down-migrations — rollback is the backup. Every release names the oldest upgrade source it supports (D10), which is how interim code finally gets deleted. The runner's own release carries none; ADR-017 D7's updateSchedule object is the first (D12). |
| ADR-024 — Site Fabric | Draft — placeholder | Several Administrative Domains cooperating — the backup-buddy case generalised. No content decided. |
| ADR-026 — Managed Machines as Modules | Proposed | Every machine TAPPaaS manages is a module of kind: machine — cluster nodes, the satellite, and a Debian host carrying a PBS. Adds debianhost for the OS lifecycle. |
| ADR-027 — Module Blueprint | Proposed | What every module is made of, apart from its documents: the executable artifact set with MUST/SHOULD/MAY on each, the six files of a services/<service>/ directory, all of it co-located in the module's directory, and one blueprint check for every module plus a sweep to make the estate meet it. Documents are ADR-013's, contribution files ADR-015's. 00-Template is the blueprint in files, and its stubs warn that they are stubs. |
| ADR-028 — Release Cadence and Patching | Accepted | When TAPPaaS releases and how patches reach a site. The two OS families work by opposite principles: a Debian machine is changed in place and patches itself every sweep (three apt paths — guest, managed machine, locked-down vault), while a NixOS machine is built, not upgraded — it holds no flake and no channel of its own, update-os.sh forces one revision onto it, and rebuilding against the same revision changes nothing, so NixOS patches arrive only when a human moves a lock. Decides: one estate pin (templates/flake.lock, the mothership's flake following it, keeping its own build path for upgrade safety); an unstable → staging → production train on two-week boundaries (the branches main → staging → stable), putting production at most four weeks behind, where a CVE accelerates the train rather than cherry-picking a pin onto code it was never built against; a guest proves each revision before the mothership takes it; the ref stays a Hydra-built nixos-* channel so guests substitute instead of compiling; and the #680 pin-age tripwire tightens to 45 days, which detects branch EOL for free. Opens: the control plane can still not roll itself back (D10), and the satellite's dead --os nixos remains should go (#712). Includes a primer for readers new to Nix. |
| ADR-029 — NFS Service | Proposed (v0.9) | NFS shares for consumer guests, by share name: share names are unique across the Site, each has a DNS alias nfs-<share>.mgmt.internal to its server, so a module ships one mount to every site and survives a share moving. v0.9: the declarations are Site state — config/shares.json, owned by a new storage-manager whose verbs change one share at a time (nfs share add/modify/delete/purge, nfs grant/revoke, nfs show), the start of a storage control plane that can grow beyond NFS and beyond PVE hosts; consumers depend on storage:nfs from a virtual storage module (registered like cluster; the PVE nodes deliver the service); a server module only implements a hook that builds what is declared for it (pvehost in v1). A missing share leaves a mount pending; one that appears later is migrated into with consent. Access derives from one grant (two-key check, a tcp/2049 rule to the alias, a client list of the deployed consumers that mount it, squash-to-owner); NFSv4, root_squash; TLS deferred (#771); data is only destroyed by an explicit purge. |
| ADR-030 — IPv6 | Accepted (v1.0) | IPv6 for a site, behind the site.json ipv6 switch. The WAN is declared in site.json network.wan: dynamic (DHCPv6 and a delegated prefix, the default) or static (a fixed WAN address and a routed prefix), or none. The site prefix must be /56 or larger; zones take their /64 from its first /56 by an ipv6Subnet number (0–255) that every zone gets by default and an operator removes to keep a zone IPv4-only. Devices use SLAAC; VMs get AAAA names; published names are dual-stack inside the site, and Caddy answers on the WAN's IPv6 address from the internet. Firewall rules and anti-spoofing cover both families; switching off withdraws each zone's route first. ipv6-manager converges all of it in the network update. |
| ADR-031 — Site Liveness from the Backup Buddy | Accepted — implemented | A dark site cannot report itself. Every site's backup node runs a pulse: it probes the PBS of each buddy it pulls through the buddy tunnel and mails both operators when a buddy stops answering, checks its own site (uplink, firewall, mothership, own PBS), and on the pulled side watches when the buddy last pulled. A standalone pulse covers a buddy that is not TAPPaaS. |
| ADR-032 — Service Exposure | Accepted (v1.0) — built | ADR-023 stays the model and gains three things: the identity gate authenticates machine callers (an Authentik service account and a client-credentials JWT; identityGate: false only for webhooks, with a reason); a module without network:proxy is unpublished by design, and one that runs third-party code without user data lives in the DMZ (ADR-021 R1 amended); Jellyfin is published without the gate so friends and family can use its apps (SSO for the web, Quick Connect for apps, hardened at Caddy and in Jellyfin). P0 tests done. |
| ADR-034 — TAPPaaS User Interface | Accepted (v1.3) — built, live on hrossen; D11 module page sections in progress | One web UI for a site, console: a TypeScript backend on tappaas-cicd as tappaas with a React front end, published through Caddy and the Authentik gate as console.<domain> for operators from mgmt and the admin VPN only (from elsewhere the login, then 403; the tunnel needs the site's DNS, #856), with status.<domain> read-only for the site owner once a further route can be gated, roles from Authentik groups with destructive verbs behind a typed name. It operates only through manager verbs: every change is a job with the manager's own dry run as preview, recorded in Activity. The physical view is derived from network-manager topology, shared with G6.1, and drawn with React Flow; the service catalog (#183) is the Modules page, Backstage (#91) is not adopted; the assistant runs through LiteLLM and proposes, never applies; agents (#142) use the same API through the gate with scopes. P1 to P3 (see, operate, ask) are built. |
| ADR-035 — Pluggable Controllers and Managers | Accepted (v0.10) | A module brings its own control plane: controllers and managers live in the module in tappaas-cicd's layout and use its shared libraries, are declared in its JSON, built, linked into ~/bin and recorded in one registry (config/control-plane.json) by module-manager, and register with the manager that drives them, code and instance. A controller is <application>-controller; a taken name is refused, for managers and controllers alike, while copies of one module share one registered controller. A controller from an unverified repository plugging into a foundation manager is a warning. Ansible is an option, not the default; a controller's own declarations live in <name>.json. First UniFi (in the Community unifi-os module — not FLOSS, so not in TAPPaaS), then mikrotik-controller with Ansible. Answers #430, #731's registration; first uses #847 |
| ADR-036 — Locations and Placement | Accepted (v1.5) — built | Where a thing is has two parts: a location (a place with an address: the site's building, a provider's data centre, a backup buddy's site) and a placement inside it (room, rack, unit). site-manager owns the site's locations with a primary one; every physical device (a machine, which includes the cluster's nodes as their pvehost instances, a switch or AP, a recorded device) names its location by name on its own record, absent meaning the primary; rack-manager becomes position-manager, owns positions.json with rooms in a location, racks, every placement and the recorded devices, and no other record carries a room or rack. The topology is the one joined device list, with unrecorded devices seen at ports promotable to records. The console draws locations, then rooms, then racks. Resolves findings 2 and 3 of src/DATAMODEL.md. |
| ADR-037 — Install | Accepted (v1.2) | A node with one disk (or one mirrored pair) is a site: ZFS on the boot disk is the default and required without a data disk, and a module's storage is a preference — the same class, any tanka<N>, any other ZFS pool, then the boot pool, with a warning and the placement recorded; every zfspool works by its storage name. A rented server (Hetzner Robot) runs on its one IP: at the cut-over the firewall VM takes the server's address and MAC, the node keeps a generated MAC and sits behind the firewall on a lan with no port, with a rollback and a boot watchdog that give the address back; the operator comes in through the first admin-VPN peer; two servers meet on a vSwitch VLAN. install.sh ends at the console with its setup token; the rest of the install is the Setup wizard (ADR-034 D10), the scripts kept behind --all; the bootstrap can be run again. |
| ADR-038 — Component Declarations | Proposed (v0.3) | Amends ADR-035 D11: a controller's or manager's own <name>.json (or, for a module without a component, its declarations.json) is described by a JSON Schema subset with changeClass, key and references annotations, no secrets. Each instance has its copy in config/declarations/<instance>/, seeded on install and three-way merged on update. module-manager is the one validator (blueprint, install, update, declaration set); module-manager declaration set <instance> <name> <path>=<value> changes it under its class and has the owner apply it (reconcile, or the module's update.sh), with rollback; the console renders it from the schema. The module JSON stays the platform's. Answers #899 |
| ADR-039 — Module Alerting | Accepted (v1.0) — P1–P5 built and live | A module ships <module>-alerts.json: rules that name a line pattern, an optional unit and captured labels, a window, an event/state kind and optionally the mail's subject and body as placeholder templates (a rule may include anonymized log lines and the support bundle; lines only where the site opts in) — never LogQL. The platform builds the query over the module's own hosts (foundation modules may also scope to the nodes or every host, attach a bundle, or give an expression), provisions one Grafana rule group per module through the API, mails to site.json's recipients through the existing receiver, and lists open alerts per module, machine and cluster (health-manager alerts). The foundation's own rules move to the modules they belong to (pvehost, cluster, network, backup, logging), tested against today's rules and mails; the firewall and the nodes declare logging:logs as syslog senders. Answers #904 |
| ADR-040 — Asset Lifecycle and CMDB | Accepted (v1.5, 2026-10-31) — implementation in progress | TAPPaaS's lifecycle follows the IT4IT 3.0.1 Digital Product Backbone: module and ADRs (Digital Product), the module's design (Product Design; Codeberg issues beside it as backlog items and defects, tied to the design and to releases), module and repository releases (Product Release), config/ (Desired Product Instance), and the actual state as a CMDB (Actual Product Instance) kept by a new cmdb-controller, a 24/7 API service with the cmdb CLI in front of it, that every manager reports observations and changes to. One store, three roots: CIs (a module is a node of its kind — vm, lxc, machine, device — with software running in it: app, service, controller, manager; network and storage elements; identity; collection), resources — IT4IT's Resource, kept beside the CIs as the industry does: the physical assets with their ports, and pools later — and places; a small class hierarchy with inheritance and typed relations, the metamodel stored as data (a class is rows, not tables, so a module can add one), history, drift and a trace back up the backbone. Two lifecycles kept apart: an asset's (ordered to disposed, allocated to a CI or free, reusable) and a CI's (created from its desired record, retired with it, never reused). position-manager becomes asset-manager. The console's views, Physical and Assets included, read the CMDB; events name their CI; every CI has an OpenTelemetry resource identity that Alloy carries. Built in TypeScript on PostgreSQL, TAPPaaS's database standard, borrowing IT4IT, UCMDB's shape, CIM, NetBox and OpenTelemetry. |
| ADR-041 — Health in the CMDB, Root Cause and the Health View | Accepted (v1.5, 2026-11-09; every open question closed) — implemented, on main since 2026-11-01, live-tested; D5 redesigned as tree + ego graph |
Health becomes data on every CMDB object: Kubernetes-style conditions (operational, drift, capacity, security, maintenance, backup, and a derived impact), with history. health-manager splits into assess (the gates, ADR-039's open alerts, the sweep's drift, thresholds over the controllers' observations, the CVE scan → conditions; the only writer) and emit (one event per transition, typed causal/symptom/recovery as IT4IT's Event; ack, flapping, maintenance; the read verbs); validate becomes a read. Root cause is derived along the typed relations — an object failing because its required provider failed is impacted, not failing (Icinga's unreachable), the root is the failing object no failing provider explains — no learning, no time windows. A Health menu entry under Day 2: a containment tree with roll-ups, an ego graph one hop deep around the selected object with plus/minus expansion and shortcuts to the root cause and to what it impacts, and the CI panel; live. Surveyed Zabbix, Icinga, Checkmk, Nagios, Keep, Alertmanager; adopting none. |
| ADR-042 — Disks as Assets and CIs | Accepted (v1.0, 2026-10-31) — a disk is an asset (serial, a bay in a server as its placement) and a disk CI a pool is built-on, one redundancy group per vdev; the disk is the root cause |
|
| ADR-043 — Site Certificates | Accepted (v1.0, 2026-11-06) — implemented, live on hrossen (internal CA, logging over TLS); one internal CA on every site, plus a CA per domain tree with no public certificates; ca-manager owns all certificates and the DNS providers; dnsMode only chooses the issuer of published names |
|
| ADR-044 — Scaled Deployment Sizes | Accepted (v1.0, 2026-11-06) — built, live on hrossen; the 32 GB install at small passed | A site and each environment are small, medium (default) or large. A module's cores/memory/diskSize are the medium values, with optional coresSmallLarge/memorySmallLarge/diskSmallLarge pairs; install takes the small value for small and the large value for large, an operator's value wins, and update re-sizes the release before the 3-way merge so sizing is never a pin. Foundation + home + office fit a 32 GB node at small. |
| ADR-045 — CVE Lifecycle and Risk Scores | Accepted (v1.0, 2026-11-07) — implementation started | The boundary removes VEX statements no channel needs, lists those a version change made inapplicable (carried, re-pinned by one confirmation) and archives its acks in releases.json. One risk score: risk 25/10/3/1, open 20/8, only the highest category counts and each further item halves; levels at 7/16/30. A zone is its highest module times its tier's multiplier (tier 0 ×2 … tier 4 ×0.25, tiers 5–6 ×0.1), an environment its highest zone, the site its highest environment or unassigned zone. Health, two new alerts and a live /security page use it; analysed low/medium items pass the gate without an ack. |
| ADR-046 — Performance Monitoring | Accepted — implemented (v1.0, 2026-11-18; P1–P6 on main since 2026-11-11, web services measured by default since 2026-11-17), #927, #929 |
Performance as a third signal beside logs and events: logging:metrics (Prometheus; guests push through Alloy, Proxmox and PBS through their metric server, all with the CI's OTel identity) and an idle logging:traces; USE for resources, RED for published services; performance.level off/basic/service/trace set per site, environment and module (small off, else service), fine resolution standing or timed, trace only timed per CI; CMDB changes as chart annotations; a Performance menu in the console (overview, browse, levels, investigations); a performance condition with static thresholds and source: metrics rules feed ADR-041 and ADR-039. |
| ADR-047 — CVE Decisions and the Daily Work | Accepted (v1.0, 2026-11-12) — D9 built | The component (one upstream project as one module uses it) is the unit of a central CVE decision, with a use statement, rules on the CVSS vector, an author and a review date. A decision is a reclassification to the same level, a lower one or none, and a CVE is scored by its effective level alone (20 / 8 / 3 / 1). VEX is generated from the records. A site checks a record's deployment assumptions itself and can accept what is left, with a date, which lowers its score. The Security view is a list of actions, and a daily check proposes pin moves. The rescan matches by source package and "new" means first seen. |
| ADR-048 — The Security Stream | Proposed (v0.4, 2026-11-11) | Development (unstable, staging) moves to a private forge. Production exists twice: a subscriber line with daily security, decision and operation-affecting bug patches, and a public line on Codeberg with the same feature releases at the same boundary and each patch 14 days later; a known-exploited fix goes to both at once. rel/ and sub/ branches per release held together by a tree check, gates (build, hrossen, a two-day canary ring, a signature), a signed decision feed, per-site tokens with fallback to the public line, plain MPL-2.0, and the roadmap and ADRs still published at once. |
| ADR-050 — Security Monitoring | Accepted (v1.0, 2026-11-12) | The SIEM in two layers, layer 1 built first: security detection on the logging stack at medium and large, off at small (a rule pack on ADR-039, CrowdSec bans, Suricata IDS, auditd and a closure check), findings as security conditions on CMDB objects; Wazuh as an optional module at medium and large, future work. Analysis in docs/plans/siem-analysis.md. |
| ADR-051 — Disk Encryption at Rest | Proposed (v0.7, 2026-11-14; no open questions), #928 | Pools on a node built on LUKS2, ZFS on top, rpool included. A setting per site, node and pool, off at small; the pool is the unit, so a node may mix, and encryption can be added to a pool later (disks that held data wiped first). The Proxmox installer stays: a two-disk rpool is encrypted after it, a one-disk rpool stays plain for now. A volume opens by the TPM alone (risk accepted: a stolen server opens), by the TPM and an alternative key held off the server (by tappaas-cicd, except for its own boot path, or by a device on the LAN: a key device or the operator's computer), or by hand with the recovery key, kept in tappaas-cicd's escrow and on the key backup for SSH or console. No key holder off the site. A restore never needs a disk key. Snapshots, replication and HA unchanged; a retired disk is crypto-erased. Includes an analysis of LUKS and ZFS-on-LUKS against ZFS native encryption. |
| ADR-052 — Immutable Security Logs | Accepted (v1.0, 2026-11-17) | Loki stays the store to search; at medium and large, Alloy on the logging VM also sends the security streams, every 60 s, through a local rclone crypt relay to a Hetzner Object Storage bucket with Object Lock in compliance mode, versioned and locked for the security retention. The site encrypts, with the archive key kept beside the backup keys; its S3 key can write but not delete. No archive at small, no satellite fallback. Loki's delete API is turned off. A daily health check on the archive's freshness, encryption and lock mode; an archive fetch --compare verb finds lines missing or changed in Loki. |
| ADR-053 — Backlog Board Module | Proposed (v0.7, 2026-11-18; P1 and P4 verified on hrossen; P5 roadmap-from-Vikunja being built) | Vikunja is the devops stack's kanban and backlog board, chosen over Tenzu, Taiga, Planka, Plane, OpenProject, WeKan, Kanboard and Leantime (licence, free OIDC, NixOS module). A NixOS VM (VMID 354) from the release's services.vikunja and package; Postgres over a socket, daily dump; published to the internet. Sign-in with Authentik only, local login off once the client exists. The Authentik group devops becomes the Vikunja team devops through a new identity.teamClaim field (a filtered team claim, named per instance); an environment of another organisation gates on its own group with gateGroups. Pro is the operator's choice; no license check leaves the site without a key. Ships as Development. Tenzu is looked at again once it has sprints and issues. |
Governance
| ADR | Status | Decides |
|---|---|---|
| ADR-011 — SBOM Governance | Proposed | What is running on an installation and which of it needs a fix: generated per installation, one scanner per layer (Nix closure, image, Debian host, OPNsense), coverage-checked, triage committed as VEX. |
| ADR-013 — Documentation Structure and Standards | Accepted — implemented | Where documentation lives, which artifact serves which audience, and how the site syncs from source. |
| ADR-033 — Signed Releases and Verified Updates | Accepted (v0.9) — signing since v2.3; Erik's keys being enrolled | Supply-chain integrity: staging and production release tags are SSH-signed by the TAPPaaS owners with keys kept in their own vaults (one-year life), plus an offline emergency key each, on their offsite backup-key stick, that can only enrol or revoke signers; each repository records its signers in .tappaas/allowed_signers, changed only by a previously trusted signer; first trust is the owners' published fingerprints in site.json; a site that skips releases follows the chain of releases between; the update verifies before any checkout moves and refuses rollback; built images ship a signed SHA256SUMS and are checked by hash; nixpkgs is covered through the signed flake.lock and Hydra's keys; every repository's signing status is a health-manager check and a validate gate. |
| ADR-015 — Community Governance and Contribution Files | Draft | The community-health file set (CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, GOVERNANCE, CODEOWNERS, templates) — names, per-repo placement, and contents, plus the per-module AUTHORS.md. The companion to ADR-027, which defers every contribution file here. |
Writing a new ADR? Decide in writing first, before the code; the process and standards are in ADR-013 — Documentation Structure and Standards.