Roadmap¶
What we are building, in the order we build it, and what each release has delivered — the open work at the top, the releases below it.
The current plan is security and stability. It is built in waves: first make upgrades safe, then make the breaking changes while few sites depend on today's shapes, then harden the network, then stability, then new capabilities. A filled marker means work in the wave is done and waits for the next release; a hollow one, nothing in it is done yet. Every two weeks the next version is cut for staging and reaches production two weeks later. Press + on a card for its groups and their issues.
Hosting and community modules
What a site needs to run many instances of one module and modules written outside TAPPaaS — hosting first — and a first install from wherever the operator sits. Not ordered by upgrade risk: a group lands when its first user needs it.
3 groups 11 openGroups and issues
G8.1 Containers as modules
Containers as full modules: volumes that keep snapshot rollback, linked clones where they help, and high availability for containers.
G8.2 Module contract for many instances
One contract for many instances of a module and for modules from outside TAPPaaS: a VMID range per module, zone-aligned ranges on new installs, who owns a module's dependencies, a module's own validated configuration, and proxy routes with extra hostnames, redirects and wildcards.
G8.3 Install from anywhere
A first install from wherever the operator sits: the first node's LAN uplink chosen on Day 1 instead of guessed, an install from a Windows PC, and downloaded images reused instead of fetched again.
Enhance the stacks
New modules and significant upgrades of existing ones: what a site can run, beyond the foundation and its fixes.
2 groups 3 openGroups and issues
G7.1 DevOps stack
Forgejo gets its CI: a Woodpecker module wired to it, whose agents can also build TAPPaaS itself, and Forgejo on PostgreSQL when load asks for it.
G7.2 New and reworked app modules
New and reworked app modules: a Markdown website, N.O.M.A.D. for the home stack, Karakeep for bookmarks, and a declarative control plane for LiteLLM.
- #170 LiteLLM declarative control plane
Site fabric and user experience
The physical site and how an operator sees and runs it. Not ordered by upgrade risk like Waves 0–4: these two groups are designed together — the fabric is what the physical view shows and changes.
3 groups 17 open 1 done for 2.5Groups and issues
G6.1 Switching fabric, WAN, ISP & site operations
The links a site stands on: node uplinks bonded under lan, switch ports and trunks kept in line with the zones, and the WAN and the ISP — public DNS that follows the WAN, mail when the ISP blocks port 25. Switch setup needs a systematic model, at install and on day 2. Operating the site belongs here too: a service desk and a SIEM, Wazuh the best candidate. Linked to G6.2: the physical view shows and later changes it.
- #383 Keep wildcard public DNS current on dynamic WAN
- #830
environment-manager: no verb creates the public DNS record - #125 Mail relay via M365 Graph API
- #668 A machine's zone is recorded, not enforced
- #697 Node
lantrunks and their switch ports are set once at install, maintained by nothing - #706 A wireless device zone cannot be checked against its SSID
- #158 Multi-NIC module firewall rules
- #236 RADIUS MAC Auth Bypass: a device's VLAN from its MAC, on Wi-Fi and wired ports
- #63 Service desk tooling spike
- #843 Create a SIEM for TAPPaaS
- #883 A debug bundle for support: the log and an anonymized
~/config, attached to the failure mail - #918 A repository that fails to sync stops the nightly update with no alert that names it
G6.2 User interface & physical view
A general TAPPaaS user experience, starting with a physical view of the site: nodes, bonds, switches and ports, APs, WAN and satellite, with zones, guests and live state on them, designed first in a spike and an ADR. The service catalog and Backstage are decided against it. Linked to G6.1.
G6.3 Data model
The meta model of the configuration, written down in src/DATAMODEL.md: every JSON, which field names which object, and the places where the model says one thing twice, fixed or parked. Where a thing is becomes two things, a location and a placement (ADR-036). Linked to G6.2: the console's Physical view draws what this group models.
- #866 Data model: parked simplifications (backup cascade, module placement,
module:service) - #906 Asset lifecycle and CMDB: the actual state of the site (assets, nodes, guests, modules, zones, environments, people) in a CMDB along the IT4IT backbone; an asset from procured to disposed, whether or not it is a node, switch or device at the time; ports and Wi-Fi on the asset; an asset-manager beside or replacing position-manager
Enterprise scale and tests
What a site needs beyond one node, and the tests, proofs and sign-offs on real systems, kept apart from development and bug fixes: what is built and waits for a real VPS, a real buddy, a second disk or a real failure, and the test conventions themselves.
3 groups 14 openGroups and issues
G5.1 Satellite & off-site
Everything the satellite and the off-site copy still have to prove: the satellite as a module on a real VPS, makerfloss's satellite converted, the site-liveness watchers in a real outage, the buddy tunnel and relay, the SSH port passthrough and the hardening sign-off.
- #671 Deep test: satellite as a module on a real VPS
- #776 Report a site that has gone dark (outside heartbeat)
- #796 backup: a buddy's WireGuard tunnel set up with the peer (
peer add … --tunnel) - #795 satellite: relay a buddy's WireGuard tunnel to the home firewall
- #406 ADR-010 P7 hardening + sign-off
- #762 satellite: build the
sshPortSSH passthrough totappaas-cicd(ADR-010 §4.4.2)
G5.2 Test coverage & conventions
How tests run — a test verb on the managers — and the module tests that still miss their conventions or probe the wrong thing.
G5.3 Enterprise scale
Placement and resources for a site of several nodes: guests placed and rebalanced by PVE 9.2's load balancer over a list of candidate nodes, falling back to a module's small values when no node can fit the full ones, the boot mirror proven to survive a lost disk, and memory ballooning as an opt-in.
Additive capabilities
New capabilities with low upgrade risk.
2 groups 6 openGroups and issues
G4.4 Storage & physical devices
Shared storage as a managed part of a site: the rest of the NFS service, NFS over TLS included.
Stability & correctness
Low upgrade risk. Build continuously, in any order within a group.
5 groups 18 open 4 done for 2.5Groups and issues
G3.1 cluster:vm lifecycle & capacity
Guests sized, placed, started and stopped right: memory defaults from measurement, moving a running guest to another node, a readiness wait that skips UDP ports, hardware drift, shutdown and boot order, storage growth and placement, a composite-module ADR, a sweep that survives a guest restarting itself, a capacity pre-flight before the sweep, and size changes a legacy site can see.
- #403 Install on the root disk; smarter placement 2.5
- #884 More dynamic placement and resource allocation: disk and RAM per site size (
minimalTest, small, large), falling back to the minimum under constraint 2.5 - #907 ADR needed: resource allocation — pools consumed by allocations (storage, RAM, CPU, addresses, VLANs)
- #761 A composite-module ADR:
cluster,kubernetes, and modules that only provide artefacts
✓ G3.2 Identity & SSO wiring
Every app wired to the identity provider the same way: OIDC for Nextcloud and forgejo, a site-specific login page, logging's SSO dependency, a test for forward-auth, and Jellyfin behind forward-auth with Authentik sign-in.
G3.3 App module fixes
The known rough edges of the app modules, fixed and tested so they stay fixed: Nextcloud Talk end to end, Home Assistant (maintainer-owned fixes, locale from the site, OIDC staging), Nextcloud and euro-office, litellm consumers, windows-server, forgejo, in-guest backups and container stop timeouts.
- #552 hass: a lost LLAT blocks every update
- #568 hass: backup freeze leaves Frigate unhealthy
- #571 hassanova has no release baseline
- #348 hass locale from site master data
- #345 hass: appliance-aware OIDC staging
- #553 litellm:models cannot reach an appliance consumer
- #715 Nextcloud-hub revisited: Talk never worked end to end; races, retries and tests hid real failures
- #411 windows-server:
deploy-instances.shmissing - #754 In-guest backup timers: drop for PBS or say why they stay
G3.4 AI stack maturity
A production-grade AI stack: hardened and kept current, LiteLLM sized for its workers, and vLLM's models recoverable after a restore.
- #121 litellm production-grade
- #621 Bump litellm / openwebui 2.5
- #812 vllm-amd: privileged LXC, unauthenticated vLLM API, sshd password auth
- #758 vllm-amd: the models bind mount is in no backup
- #677 litellm's default workers do not fit its default 4 GB
- #846 vllm-amd: a new API key does not reach LiteLLM; its tests stay green
- #800 litellm:
trusted_proxy_rangesand env-credential login (1.103 warnings) - #828 litellm: the UI accepts the master key as a static admin login
✓ G3.5 Installer UX
A first install that is easier to get through: a first node that can be run again, that shows its progress, and that asks only what the hardware needs. A bootstrap that resumes from any step is ADR-037 P3b.
- #377 Installer cannot restart; mgmt-net routing 2.5
Network behaviour hardening
Changes to live firewall and DNS behaviour on every installation. Restrictive defaults get harder to introduce the longer users rely on permissive ones, so they come early; every change shows its dry-run diff before --apply.
Groups and issues
G2.1 Firewall exposure & rule order
Tighter firewall defaults that keep what modules need: the gateway, GUI/SSH and anti-spoofing rules, pinholes that nothing shadows, IPv6 in every zone policy, a reviewed tier model and rule creation, a rules manager that reports overlaps, covered pinholes and rule order, IP blocklists from site.json, a module's egress narrower than its zone's, and CrowdSec's community list as an opt-in. The NetBird rules are low priority until the NetBird decision.
G2.2 DNS resolver robustness
A resolver that holds up: a working Unbound restart, a written IPv6 stance, DNSSEC with split horizon, and DNS blocklists kept fresh, with one threat-only list on by default for new sites.
The breaking-change window
Everything that renames, re-schemas or rebuilds, landed while few installations depend on today's shapes — each change with its migration and an upgrade test from the current stable, not only a fresh install.
Groups and issues
✓ G1.2 Backup placement model + managed machines (ADR-012, ADR-026)
Backups where the operator chooses — a node, a managed machine, an external PBS or the satellite — encrypted, with every machine TAPPaaS manages a module (ADR-012, ADR-026).
G1.6 Secrets & privileged access
Least privilege on the platform: nodes hardened to the Proxmox guide, key-only SSH, encrypted backups, and a decided way for an AI agent to reach the mothership; the site's CA verified on the firewall API and on log ingest, and one way for every module to reach its secrets.
✓ G1.7 Parked for Erik discussion
Waiting on a conversation between Lars and @ErikDaniel007, not on work: the controller pattern.
- #765 Container image pins: list litellm, openwebui, vllm-amd, deconz; move the stale ones 2.5
TAPPaaS 2.4
Sites update daily at 02:00 by default: a site still on the old weekly default (Tuesday or Thursday at 02:00) moves to daily on its first update, with a warning that names how to keep weekly; any schedule chosen otherwise stays.
v2.4 in stagingWhat it carried, by group
Tag v2.4, cut into staging 2026-11-09 by a release-train boundary.
Sites update daily at 02:00 by default: a site still on the old weekly default (Tuesday or Thursday at 02:00) moves to daily on its first update, with a warning that names how to keep weekly; any schedule chosen otherwise stays. An update no longer keeps a configuration value nobody chose: when a release starts to define a field the site already has with another value, the release value is taken and the update warns with the value it replaced, unless the operator set it with module modify --set, which now records the fields it sets. Every way a repository moves now goes through the signature checks: a repository that site-manager clones again, or moves to the branch site.json declares, is verified like an update, and a staging or production clone without recorded signers is refused with the command that adds it.
Every site gets its own certificate authority. ca-manager owns the site's certificates and its DNS providers, whoever issues them; acme-setup.sh stays as a shim, and the old credential file moves into it. Logging takes its journals, queries and syslog over TLS with the site CA's certificates; the plain ports close a release later. A new site starts in local DNS mode, and without a domain it is <site>.home.arpa throughout.
The site's actual state is kept in a CMDB: assets and CIs, disks included, fed by every manager and checked by a discovery sweep. Health becomes conditions on those objects, with root cause along their relations, shown in the console's new Health view.
A module can ship its own alert rules as line patterns, and the foundation's alerts are written that way too; health-manager alerts lists what is open and what fired. Containers are watched like VMs: health gates, journal shipping, backup listing and purge, and the update's boot wait reach them through their node.
In the console, Day 1 follows the confirmed order and ends with the rest of the foundation placed on the machines; Day 2 gains Add a repository and Add a switch. A memory-tight node holds back only the module that grows, and modules can be paused to make room.
A hard stop of the mothership no longer leaves a repository it cannot sync: git writes in the managed checkouts reach the disk, and a sync repairs empty objects and empty files from origin. A proxied name that no wildcard certificate covers and that has no public DNS record is no longer published, so the proxy stops retrying a certificate it cannot get.
The rows below are what it carried, by the wave and group they came from.
G3.1 cluster:vm lifecycle & capacity
G4.5 Governance, CI & sign-offs
- #888 site-manager: reconcile clones and branch switches skip the signature checks
G4.6 Community module extension points
What a Community module needs from the platform so it does not carry its own copy: one place for its secrets, containers watched and logged like VMs, its own validated fields and its own alert rules — the last two with an ADR each first.
- #902 Convention: where modules escrow their secrets on the mothership
- #901 health-manager: health gates that reach containers
- #903 logging:logs: journal client for Debian and LXC guests
- #904 logging: module-supplied alert rules
- #912 tappaas-alert-rules: apply crashes on a site.json with a
locationobject - #913 pbs-controller: list and purge ignore container backups
- #910 wait_for_guest_settled waits the full timeout on a container without sshd
G6.1 Switching fabric, WAN, ISP & site operations
- #905 Log alerting: a rule whose query cannot run mails under its own name; a Loki that is down slips past the watchdog
- #919 A checkout with empty git objects cannot be synced or repaired
- #920 A hard stop of the mothership leaves zero-byte git objects and files
- #921
network:proxyretries ACME forever for a name no wildcard covers and with no public DNS
TAPPaaS 2.3.3
The second round from makerfloss's updates.
v2.3.3What it delivered
Tag v2.3.3, moved into staging 2026-10-26 as an urgent fix on top of 2.3.2 (tappaas-train patch, ADR-028 D12); production stays on 2.2.2 until the next boundary.
The second round from makerfloss's updates. On a site without internal IPv6 networks CrowdSec writes no site whitelist — an empty one stopped the engine at start, while its service status still named a process — and "running" now means the engine's local API answers, in the network update and in its test. Updates say less every night: backup and logging confirm their wiring in one line each, backup:filesystem in one line per guest, a CPU change held for the next restart is left to its DEFERRED warning, and snapshot pruning, pinned fields, the journal wiring of every module, unpublished names, the self-check's list and a reboot pass with nothing to do are [Debug] or one line. module-manager's own steps stay as they were.
TAPPaaS 2.3.2
The fixes from the first update of a staging site to 2.3.1 (makerfloss).
v2.3.2 in stagingWhat it carried, by group
Tag v2.3.2, moved into staging 2026-10-26 as an urgent fix on top of 2.3.1 (tappaas-train patch, ADR-028 D12); production stays on 2.2.2 until the next boundary.
The fixes from the first update of a staging site to 2.3.1 (makerfloss). CrowdSec on the firewall downloads its hub index when it has none — without it the engine stopped at start and nothing was banned — and says why when it does not converge. A module test that fails prints the checks that failed and where its full output is kept, not the whole test. A dual-stack guest's firewall alias is compared per address family, which ends a 90-second wait and a warning on every update of a guest that mounts an NFS share. A satellite's name, host and provider are schema fields, and _note fields no longer warn. Updates are quieter: no progress dots in the log, no second control-plane refresh in tappaas-cicd's pre-update, no module banners. It also records the issues closed on 2026-10-26 whose work was already in 2.3: the controller pattern for app modules (ADR-035 accepted), signed releases (ADR-033 accepted), MikroTik with MLAG, the console's first phases, and modules for physical devices.
The rows below are what it carried, by the wave and group they came from.
G1.7 Parked for Erik discussion
- #430 Controller/manager pattern for app modules
G4.5 Governance, CI & sign-offs
- #848 Signed releases and verified updates — implement ADR-033
G6.1 Switching fabric, WAN, ISP & site operations
- #155 Modules for physical devices
G6.2 User interface & physical view
- #839 TAPPaaS user interface: a general UX, starting with a physical view of the site
TAPPaaS 2.3.1
The update sweep stops failing on what a site runs that way on purpose: a node already over its memory threshold warns (only growth refuses, and a new module's install), a suspended provider no longer fails its consumers, and a run where only app modules failed ends degraded (exit 3, still mailed) instead of failed.
v2.3.1 in stagingWhat it carried, by group
Tag v2.3.1, moved into staging 2026-10-26 as an urgent fix on top of 2.3 (tappaas-train patch, ADR-028 D12); production stays on 2.2.2 until the next boundary.
The update sweep stops failing on what a site runs that way on purpose: a node already over its memory threshold warns (only growth refuses, and a new module's install), a suspended provider no longer fails its consumers, and a run where only app modules failed ends degraded (exit 3, still mailed) instead of failed. The reboot pass finishes the cycle: in the scheduled window a guest that cannot move live is stopped, moved and started, a TSC rate the target cannot run is caught before a live move, and the waits suit slower hardware. Rollback of module modify --set restores the config from before the change. Two security fixes: the console takes who is calling from the identity gate's signed token, no longer from headers anyone on the management network could send, and NOMAD's Command Center — which can start any container — is reached only through the gate, for members of admin.
The rows below are what it carried, by the wave and group they came from.
G2.1 Firewall exposure & rule order
- #877 mdns-manager sees no
discoveryMdnsin the stored config
G3.1 cluster:vm lifecycle & capacity
G6.2 User interface & physical view
- #881 console: verify the identity gate's signed token, not the peer address
G7.2 New and reworked app modules
- #882 nomad: the Command Center behind the identity gate, fenced on the VM
TAPPaaS 2.3
A site turns it on with site.json ipv6: true (default false): each zone gets a /64 from the WAN's prefix, every VM's name resolves to its IPv6 address too, the firewall rules cover both families, names published through Caddy answer over IPv6 inside the site, and Caddy is reachable from the internet over IPv6 — publish the address ipv6-manager reports as the AAAA; everything still works over IPv4, and switching it off withdraws IPv6 cleanly.
What it carried, by group
Tag v2.3, cut into staging 2026-10-25 by a release-train boundary.
IPv6, opt-in per site. A site turns it on with site.json ipv6: true (default false): each zone gets a /64 from the WAN's prefix, every VM's name resolves to its IPv6 address too, the firewall rules cover both families, names published through Caddy answer over IPv6 inside the site, and Caddy is reachable from the internet over IPv6 — publish the address ipv6-manager reports as the AAAA; everything still works over IPv4, and switching it off withdraws IPv6 cleanly. The first sweep after upgrading turns IPv6 off on the firewall — inbound IPv6 dropped, DNS over IPv4 only — unless the site sets site-manager site modify --ipv6 true first. Existing zones are given an IPv6 number (migration 0016); it does nothing while ipv6 is false. See IPv6 and Firewall Rules on tappaas.org.
Firewall and DNS. Unbound validates DNSSEC: the first sweep turns it on (site.json dnssec, default true; set it false to opt out); internal and published names are unaffected. A zone can share mDNS discovery with other zones ("mdns": true; discovery only, reach is still the zone rules). A client zone can serve several environments (serves as a list, network-manager bind --add). A module's aliasType can now be changed and is applied in place; ports on a module without network:rules is documentation and no longer warns. rules-manager overlaps reports shadowed, redundant and conflicting rules, and a pinhole a zone's access-to already covers is no longer written. Every zone with internet access now also blocks CGNAT, link-local and the firewall's own addresses, and a module's egress to: internet excludes the site.
The console. A web console at console.<domain>, behind the Authentik sign-in and reachable from the management zone and the admin VPN only: the site's physical and logical views, its modules, updates and repositories, and every manager verb as a job that is previewed before it runs; a destructive verb asks for the object's name. Before identity is installed, a one-time setup token on the mothership opens it for the rest of the install.
Signed releases. A checkout on a staging or production branch moves only to a release tag signed by a key that the last verified release lists, and never backwards; a fresh clone starts from a signed introduction. The health check reports every repository's signature state and keys about to expire.
Cluster. A second corosync link; a QDevice gives a two-node cluster its third vote, and node add warns when a cluster has only two. USB network adapters can join the LAN bond, and node network set --wan-port chooses the WAN port. HA places a guest only on nodes that carry every bridge it uses and no longer moves a host-CPU guest live onto an older CPU. The sweep refuses an over-committed node, and guest disks grow automatically.
Modules. New: Karakeep (bookmarks and read-later, tagged by the AI stack), Woodpecker CI beside Forgejo, lazysite (a Markdown website from a Forgejo repository) and Project N.O.M.A.D. (an offline knowledge library). Jellyfin moves to 12.2 with the maintained SSO plugin and is published without the identity gate so its apps can sign in; its database is migrated on the first start and cannot go back — the pre-update snapshot is the way back. CrowdSec on the firewall bans repeated failed logins and probing on published names. A route can be limited to paths, to zones and to a provider's source ranges. module-manager gains suspend and resume, add-stack, and migration by changing a module's node.
Security. Images move to current releases (Authentik 2026.8.5, Karakeep 0.34.1, Meilisearch 1.55 — its index is converted on the first start — and lazysite 0.16.0), and the CVE scan now sees native libraries bundled inside Python packages. Two risks are documented in their install guides: the console believes the identity gate's headers from the firewall's address, so the management zone must hold only TAPPaaS's own machines; and NOMAD's Command Center has no sign-in and controls the VM's Docker. A guest moved live onto an older CPU may run without some CPU-side mitigations until it next reboots.
The rows below are what it carried, by the wave and group they came from.
G2.1 Firewall exposure & rule order
- #816 Review the zone tiers and rule-set creation; publish how it works
- #386 block-private rules shadow auto-pinholes
- #815 IPv6 parity: zone policy covers IPv6 before any zone gets an address
- #817 Egress
to: internetalso passes every private and zone network - #818
alias:peers skip the zone-policy check - #819
alias:ingress bound tolan; a failed interface lookup falls back silently - #820 A description change duplicates a module rule
- #821 The pinhole check exists twice and the copies can disagree
- #822 Block-private misses 100.64/10, 169.254/16 and the firewall's other addresses
- #823 Gateway lookup is one unretried API call per zone
- #824 Amend ADR-014 and ADR-021 to the zone and rule model as built
- #576 Zone
servesas string or array - #257 mDNS in zones.json
- #160 Overlap detection in the rules manager
- #256 Skip pinholes already covered by zone access
- #162 Persistent sequence-map artifact
- #660 A declared
aliasTypechange cannot be applied - #683 Declared
portswithoutnetwork:rulesare inert
G2.2 DNS resolver robustness
G3.1 cluster:vm lifecycle & capacity
- #531 Detect hardware-spec drift
- #827 HA failback can move a host-CPU guest live to a node with an older CPU
- #100 Automatic storage extension
- #833 Sweep pre-flight: refuse an over-committed node; a minimum host size
- #834 First converge on a legacy site applies config sizes over those tuned in Proxmox
- #832 Field report: a 2.0 site upgraded to 2.2, then a second node
- #663 Memory defaults are not based on measurement
- #825 update-module: changing a running guest's node does not migrate it
- #826 Readiness wait probes UDP ports over TCP — 180 s lost per update
G3.2 Identity & SSO wiring
G3.3 App module fixes
- #332 euro-office / Nextcloud install findings
- #807 Immich: bump
unstableSrconcejellyfin-ffmpegfixes six upload-reachable CVEs - #850 Upgrade Jellyfin to 12.x and the SSO plugin to the maintained fork
- #859 jellyfin:
jellyfin-tappaas-policyfails the activation on first run - #751 nextcloud:fileservice has no teardown
G3.4 AI stack maturity
G3.5 Installer UX
- #266 Progress indicator during the PVE update
G4.1 Alerting & cluster resilience
Be told when something breaks, and survive more of it: alerts from Loki by mail, every VM's logs in Loki with a credential per pushing VM, container severities and each line's own timestamp, a release CVE preview with majors gated at the boundary, two-node quorum with a QDevice, HA failover only to nodes that carry the guest's bridges, a site-timezone gate, and a site gone dark watched from outside.
G4.2 Proxy & ingress
Publish less of each app: limit a route to some paths, some zones or a provider's source addresses (ADR-023). One model for how a module's routes are authenticated — several ports, native app clients, machine callers (ADR-032). Decide whether an internal proxy is needed at all.
G4.3 Manager verb gaps
The verbs operators otherwise do by hand: install a whole stack, suspend a module, migrate by changing .node, private repositories and module-level --set rules.
- #763
module-manager add-stack: install a stack's modules independsOnorder - #428 module-manager
suspend - #429 Migrate by modifying
.node - #634 Private repositories in
repository add - #654
module-manager: the--setpre-gate ignores the module-level field declarations (ADR-020 D10) - #831
module-manager delete: an archived module still counts as a dependent - #857 Every update on main rolls back:
suspend-module.shcommitted without the executable bit - #852
modify --set zone0fails its own pre-update tests - #829
backup-manager restore restoreover a module's own guest fails without a terminal
G5.1 Satellite & off-site
- #775 Convert makerfloss's
satellite1into a module instance
G6.1 Switching fabric, WAN, ISP & site operations
- #40 Redundant lan uplinks: a bond under the
lanbridge - #853 switch-controller: unallocated ports parked in
iotLocal; a verb to park a port;validatewarns - #854 switch-controller: a LAG member follows its lead port
- #860 switch-controller: read the switches after every sweep, so
switch-portsis not judged on a stale read - #856 admin VPN: the peer config carries the site's DNS and routes to the DMZ gateway
- #875 IPv6 egress: a health gate, and re-learning the WAN router after an ISP change
- #889 WiFi: an SSID is site-wide, owned by ap-manager, bound to a zone; passphrase change as a verb
- #731 Controller-architecture modules never register themselves, and inventory drift has no routine check
- #861 Moving a 2.2 site to main: four bugs and the workarounds used
- #862 A VLAN tag or subnet already on the firewall is not detected when a zone is authored: template
wan(VLAN 100, 10.1.0.0/24),zones init/merge, andadd - #851 CrowdSec on the firewall: rate limiting and bans for published names
G6.2 User interface & physical view
- #844 Spike and ADR: design the TAPPaaS user interface
- #855 console: a destructive verb's typed confirmation names the object, not the switch
- #183 TAPPaaS service catalog
- #91 Backstage as a component of tappaas-cicd
- #878 console: which Authentik roles give read access and which give update access
- #892 console: differentiated roles (viewer, environment operator, user editor, network operator)
G6.3 Data model
- #865 The zone names its environment;
environment.network.zoneandzone.serves[]go - #867 Drop
site.organizations: the identities/organizations directory is the list - #869 ADR-036 step 1: site-manager owns locations, with a primary one; a backup buddy's place is a location
- #870 ADR-036 step 2: position-manager (was rack-manager), placements in rooms in a location
- #871 ADR-036 step 3: every device record names its location
- #872 ADR-036 step 4: the nodes are
pvehostmachines;site.hardware.nodesgoes - #873 ADR-036 step 5: the console draws locations, rooms, racks
- #868 Faceplate catalog: a site adds plates for models the catalog lacks
- #876 A Service zone may serve several environments (shared service zone)
G7.1 DevOps stack
- #840 devops: a Woodpecker CI module next to Forgejo
TAPPaaS 2.2
Every VM and container backup is now encrypted; the firewall admits its GUI and SSH only from management, gives other zones nothing but DNS, NTP and DHCP, and drops spoofed traffic; nodes are hardened to the Proxmox guide;
v2.2 in stagingWhat it carried, by group
Tag v2.2, cut into staging 2026-10-10 by a release-train boundary.
Safer by default, and you hear when something breaks. Every VM and container backup is now encrypted; the firewall admits its GUI and SSH only from management, gives other zones nothing but DNS, NTP and DHCP, and drops spoofed traffic; nodes are hardened to the Proxmox guide; Authentik is current again (2026.8), and a CVE scan runs after every update. Alerts reach you by mail — quorum loss, failing disks, out-of-memory kills, failed backups — with every VM's logs in Loki. Guests are built on the mothership, so updates work without internet, and restores of a node and of the mothership have been rehearsed. New: NFS shares from the nodes, Immich and Jellyfin (Testing), and forgejo with single sign-on in a DevOps stack. Upgrading: each guest's first backup afterwards is a full upload, and Authentik steps through its versions over several updates.
The rows below are what it carried, by the wave and group they came from.
G0.1 Migration & rollback framework
Changes to config/ that every site can take safely: versioned migrations with backup, dry-run and a ledger (the contract is ADR-025), rollback in install and update, and one meaning for --force.
- #736 update merge pins a field that a release moves to a new place
G1.1 Vocabulary & classification (ADR-022 family)
Settle the words before they spread into schemas, CLI names and config/ paths: the ADR-022 vocabulary — kind, scope derived from stack, People → Identity — everywhere. Left for a later release: removing the tier fallback.
G1.2 Backup placement model + managed machines (ADR-012, ADR-026)
- #756
debianhost: key-only SSH as an explicit step - #760 VM and container backups are not encrypted, against ADR-012
- #737
site.jsonbackup: truefails validation and has no migration - #742
backup:filesystemupdate never creates a missing encryption key, so a capture can fail forever - #745 A dangling symlink in a declared path refuses the whole capture
- #407 ADR-012 3-node live validation gate
- #749 Installing
backupon a PVE node silently removed its PVE apt repository
G1.3 Module contract & repo layout
One module contract — what community modules copy and deployed configs point at: version and status rules, one catalogue, the blueprint check at every release, modules grouped by stack, and a tool to move them (MOVE-MODULE.md).
G1.4 Common NixOS baseline
One NixOS baseline every VM imports, carrying the site's time zone, locale, keyboard and time source — the same facts applied to Debian guests and nodes — and pins with a cadence.
- #324 App VMs do not import
tappaas-common.nix - #740
update-os.shships only*.nixsiblings, so a module cannot carry a patch or data file - #748 identity: the Authentik pin has not moved since 2026-02-21, and nothing tracks it
- #750 Container image pins have no cadence and no tripwire, unlike the nixpkgs pin
- #777 Release train: lock nixos-unstable beside the pin, so Immich 3 follows release moves
G1.5 Rebuild & recovery paths
A proven way back before anything breaking: config/ backed up and restorable, mothership keys that can be reissued, restores of a module, a node and the mothership rehearsed, and a control plane that checks itself and rolls back.
- #755
cicd-key.shignoreskind: machinemodules —rotatelocks the mothership out of satellite anddebianhost - #729 Rehearse RESTORE.md §2, §3 and §5.2 on the test system
- #314 PVE 9.2 default + upgrade path
- #417
node deletedoes not remove the node - #711 templates:nixos re-apply fails with no cause and rolls the VM back
- #720 update-os.sh hangs indefinitely when the rebuild's ssh session dies
- #700 The pre-update gate tests guests that are still booting
- #767 The sweep's systemd unit is not the operator's console — align it (ADR-017 D3)
- #768
module update: a failed dependency (the OS rebuild) should stop the update, not run update.sh first - #744 A mothership release move ends the sweep with no record, no re-arm and no notice
G1.6 Secrets & privileged access
- #128 Security hardening (Proxmox hardening guide)
G2.1 Firewall exposure & rule order
G3.1 cluster:vm lifecycle & capacity
- #392 Never attempt a disk shrink
- #393 A failed migration must not block later steps
- #532 Pending vs applied hardware changes
- #36 VM shutdown timeout
- #127 Boot order: firewall (and secrets) first
- #37 Optimise RAM (ballooning, swap)
- #423
Create-TAPPaaS-LXC.shhas nodebug() - #753 A guest restarting during its own update fails the sweep
- #793 A live migration leaves a FreeBSD guest's agent dead (firewall)
- #773
cluster:vmthinDisk — opt-in thin provisioning per module - #764 The Proxmox VM summary note links "Discussions": make the links docs, code, issues
G3.2 Identity & SSO wiring
- #282 forgejo SSO (Community repo)
- #738
identity:identitydiscovery check fails on a changed host key and blames the firewall - #797 identity: an update skips Authentik release lines when the guest is built on the mothership
- #752 identity:accessControl has no test-service
- #805 jellyfin: put the published instance behind Authentik forward-auth
- #806 jellyfin: sign in with Authentik (SSO-Auth plugin behind forward-auth)
- #794 The groups claim mapping uses
User.ak_groups, deprecated since 2026.2 - #769 vaultwarden: SSO is registered but never wired into the app
- #779 identity:
authentik-env-secrets-onlycallscmpwithout diffutils
G3.3 App module fixes
G3.5 Installer UX
- #405 Do not ask for tanks without free disks
G4.1 Alerting & cluster resilience
- #126 Alerting from Loki through the #651 channel (was: no alerts for quorum loss / node dropout)
- #165 logging v2: Loki auth, Grafana OIDC
- #788 Release train: flag a major version change at a pin move
- #770 App VMs do not ship their logs to Loki
- #784 Loki stores receive time — backfill and reboot entries collapse
- #785 Container stderr is labelled severity=error regardless of level
- #774 Build guest systems on tappaas-cicd — guests neither evaluate, compile nor download
G4.2 Proxy & ingress
G4.3 Manager verb gaps
- #759
backup-manager: no verb to take a module's backup now - #739 After reinstalling a provider,
dependsOnconsumers stay unwired - #789
backup-manager: no verb to delete a module's restore points - #790
environment-manager deleteleaves the env's DNS override, cert and refid - #791
network-manager deleteleaves the zone in other zones' lists
G4.4 Storage & physical devices
TAPPaaS 2.1
Wave 0 complete — a versioned config-migration runner with backup, dry-run and a ledger (ADR-025); honest pre-update gates; scheduled updates on a channel with an email when a sweep fails (ADR-017); a 3-way merge that can no longer skip a module silently.
v2.1What it carried, by group
Tag v2.1 (83ccb49837d1), the first release-train boundary (forced), numbered retroactively on 2026-10-02 when versions were introduced. Estate pin: nixpkgs c508844df6c2 (nixos-26.05). 718 commits after 2.0. Much of it is already in production: stable moved on to d796e254 (2.0+466) on 2026-09-18, before versions existed.
What it delivered: Wave 0 complete — a versioned config-migration runner with backup, dry-run and a ledger (ADR-025); honest pre-update gates; scheduled updates on a channel with an email when a sweep fails (ADR-017); a 3-way merge that can no longer skip a module silently. Most of Wave 1 — the ADR-022 vocabulary (kind, People → Identity); managed machines as modules (ADR-026: debianhost, module adopt, pvehost) and the backup placement model (ADR-012 v1.0); the module contract (moduleSource, the module catalogue, version/status claims, move-module.sh); site-wide time zone, locale, keyboard and time source on every guest; the move to NixOS 26.05, staged for the next boot; mothership keys that can be reissued and revoked, and key-only SSH on the nodes. Plus a first set of Wave 2–4 fixes.
The rows below are what it carried, by the wave and group they came from.
G0.1 Migration & rollback framework
G0.2 Trustworthy gates
Tests that tell the truth, so every later migration can be verified.
- #644
network-manager <verb> --helpruns the verb - #635 Pre-update gate collapses test severity
- #633
site-manager update --forceoverrides everyrebootOk - #636 backup:vm Check 1 fatal while a backup runs
- #555 network:proxy checks cannot fail without a refid
- #560 identity:identity never checks the consumer side
- #620 Tier lattice authored on 9 of 26 zones
- #645 Reconcile dry-run hides firewall rule changes
- #689 Service tests cannot tell an absent pinhole from one never requested
G0.3 Update channel & failure notice
A scheduled update on a channel, with a mail when a sweep fails — the path every later fix takes to a site.
G0.4 Merge trust
A 3-way merge that can no longer skip a module silently, so Wave 1's re-schemas reach every deployed config.
G1.1 Vocabulary & classification (ADR-022 family)
- #624 ADR-022 review comments
- #637 ADR-022 comments (second pass)
- #610 Site = administrative domain × location × zone
- #611
kindvalues; retireexternal-host(ADR-022d/f) - #599 Glossary: node vs host vs cluster member
- #628 People → Identity (
people-manager→identity-manager) - #422 Glossary rewrite
- #707 ADR-014: zone.tier has no stated relation to IEC 62443 levels
- #708 ADR-004: stack is defined three times, with three value sets
- #669
module-manager listand other verbs should handleKind
G1.2 Backup placement model + managed machines (ADR-012, ADR-026)
- #780
debianhostmodule +module-manager module adopt - #781 ADR-012 topology §1.3 verified
- #782 instance vs module name
- #665 Register cluster nodes as machine modules
- #670 Satellite as a module: retire
satellite-manager - #783
placementStaterevisit - #691 backup:filesystem ignores its schedule; every capture fires at once
- #435 backup: pass the required module argument in the deep PBS check
- #712 Retire the satellite's
--os nixospath (unpinned, untested) - #602 Empty
placementStateresolves onto the wrong host - #600 PBS on a non-cluster host
- #612
vmname→ the instance name, as a DNS alias;shimstays - #601 Placement discovery is PVE-only
- #456
externalplacement for a pre-existing PBS - #607 Exit from
externalplacement - #457
pbs_nodeuses placement, not the registered name - #603 PBS on a non-PVE host has no update path
- #554 Reconcile creates duplicate job coverage
- #609 Off-site location recorded
- #605 Split ADR-012 acceptance list
G1.3 Module contract & repo layout
G1.4 Common NixOS baseline
- #390 00-Template fails canon C4/C7
- #448 NIC rename race (kernel / udev / cloud-init)
- #472 NixOS clock two hours off
- #408 Locale/keyboard: tappaas1 is the master
- #87 NTP on OPNsense, consumed by modules
- #716 A guest can boot into a 17–34 min window with no usable time source
- #220 Nix sandbox disabled on cicd
- #680 The baseline
flake.lockdecides every site's nixpkgs - #699 Guests created with
-localtime 1boot two hours ahead - #721 promtail is removed in nixos-26.05
- #722 Grafana's
secret_keyhas no default in 26.05 - #726 A release move leaves every Postgres guest permanently warning about collation
- #728 update-os: guests switch across a nixpkgs release and fail on exit 4
- #709 Nextcloud cannot advance past 33
G1.5 Rebuild & recovery paths
- #545 Foundation backup + tested recovery (incl.
config/) - #122 Reissue and revoke tappaas-cicd SSH keys
- #43 Test and document backup/restore
- #710 templates:nixos re-apply fails with no cause and rolls the VM back
- #713 The mothership cannot undo a bad rebuild
- #725 A switch across a nixpkgs release reports failure and its rollback live-locks
- #719 The control-plane self-check does not verify what it claims
G1.6 Secrets & privileged access
G2.1 Firewall exposure & rule order
G2.2 DNS resolver robustness
G3.1 cluster:vm lifecycle & capacity
- #665 Register cluster nodes as
kind: machinemodules - #662 PVE host configuration is not backed up
- #692 A guest is built on
tanka1whatever node it lands on - #686 A backup lock fails an update that succeeded
- #679 An immutable field's schema default can make a module unreconcilable
- #569 Node capacity / overcommit verb
- #673 Cluster nodes are a fixed list of nine, not a sequence
G3.2 Identity & SSO wiring
- #698 logging update fails on makerfloss: the mgmt environment has no domain
G3.3 App module fixes
- #687 OnlyOffice: the document server cannot download from Nextcloud
- #412 coturn reads an undefined
publicDomain - #622 deconz probe uses a name that never resolves
- #714 nextcloud:fileservice fails euro-office on a verdict the run could not make
- #667
nextcloud:fileservicedeclares no fields, so its connector is undefined
G3.4 AI stack maturity
- #690 litellm VK provisioning has no readiness wait and discards the key
G4.2 Proxy & ingress
- #696 A blocked client gets a blank page: access lists carry no message
G4.3 Manager verb gaps
G4.4 Storage & physical devices
TAPPaaS 2.0
The ADR-007 taxonomy, drafted during 1.x, implemented: one Site, classified by People, Apps and Environments, with health as a cross-cutting concern.
v2.0What it delivered
Tag v2.0 (61e91f080e01), tagged and released straight to stable before the release train existed; 259 commits after 1.1. The forge milestones Release 2.0: Build out Stacks (33 closed) and Release 2.0 Documentation (3 closed) tracked it; the rest of their issues moved into the waves above.
One model and a control plane. The ADR-007 taxonomy, drafted during 1.x, implemented: one Site, classified by People, Apps and Environments, with health as a cross-cutting concern. The tappaas-cicd mothership gained the managers that run a site — module-manager, network-manager, people-manager (now identity-manager), environment-manager, site-manager, health-manager, backup-manager, satellite-manager — and the controllers behind them: opnsense-controller, proxmox-controller, identity-controller, backup-controller, switch-controller, ap-controller and the node-provisioner.
Platform. The firewall became the network foundation module (OPNsense zones, DNS, reverse proxy); the optional satellite VPS for public ingress, off-site backup and an admin VPN (ADR-010, with a Debian option); new nodes installed over PXE (site-manager node add); an unattended install; and an operator runbook to migrate a 1.x site onto the new model.
Website. tappaas.org rebuilt and served from Codeberg (cutover 2026-07-21, the day of the release).
New ADRs: ADR-003 (dependency management), ADR-012 (backup enhancement), ADR-013 (documentation structure); the ADR-007 family implemented and reconciled with the as-built code.
TAPPaaS 1.1
The collaboration hub — nextcloud, euro-office, coturn and nextcloud-hpb for Talk — the deconz Zigbee gateway, Home Assistant as a sealed appliance (hass), and windows-server;
What it delivered
Tag v1.1 (889c61a2c848), the last 1.x release; 442 commits after 1.0.
Stacks fill out. The collaboration hub — nextcloud, euro-office, coturn and nextcloud-hpb for Talk — the deconz Zigbee gateway, Home Assistant as a sealed appliance (hass), and windows-server; LiteLLM credential management, vLLM model tooling and Open WebUI 0.10. Foundation: central logging; Authentik-based identity with users, groups, roles and OIDC for modules (ADR-006); certificates through ACME.
Design for 2.0. The ADR series that 2.0 implemented: ADR-004 (module catalogue and config cascade), ADR-005 (variants), ADR-006 (identity), the ADR-007 taxonomy family (007, 007a–f), ADR-008 (switches and APs), ADR-009 (composition meta-model), ADR-010 (satellite), ADR-011 (SBOM).
TAPPaaS 1.0.0
The first release: an automated installation of a self-hosted platform for a home or a small business, running on real systems — Proxmox nodes, an OPNsense firewall, a NixOS template, the tappaas-cicd mothership, backup with Proxmox Backup Server and Authentik identity as the foundation; on top of it the first app modules: Home Assistant, LiteLLM, Open WebUI, vLLM on AMD, Vaultwarden, the NetBird client and a UniFi controller.
What it delivered
Tag v1.0.0 (682b87ce3087), the first production-ready release of TAPPaaS; 673 commits from the first one (2025-05-10).
The first release: an automated installation of a self-hosted platform for a home or a small business, running on real systems — Proxmox nodes, an OPNsense firewall, a NixOS template, the tappaas-cicd mothership, backup with Proxmox Backup Server and Authentik identity as the foundation; on top of it the first app modules: Home Assistant, LiteLLM, Open WebUI, vLLM on AMD, Vaultwarden, the NetBird client and a UniFi controller. Zones are VLANs on trunk ports (ADR-001, ADR-002).
How we plan¶
- The order comes from one plan, ROADMAP.md in the source repository: every open issue in a wave and a group, why they come in that order, and what each release carried. This page is built from it.
- Which version reached which channel, and when, is in RELEASES.md.
- Decisions are written down first, as ADRs in the source repository.
- The details live on Codeberg: milestones and issues. To influence the direction, see Contributing.