TAPPaaS

TAPPaaS Build Process

How the artifacts that make up a TAPPaaS deployment are produced: the Proxmox install media, the prebuilt VM images (NixOS template, OPNsense firewall), and — in a separate repo — the documentation site.

Two facts shape everything below:

flowchart LR
  subgraph Codeberg["Codeberg — source of truth"]
    SRC[TAPPaaS source repo]
  end
  subgraph GH["GitHub Actions — image CI + Release hosting"]
    NIX[NixOS template image]
    OPN[OPNsense firewall image]
  end
  subgraph Docs["Codeberg — Documentation repo"]
    SITE[MkDocs site → tappaas.org]
  end
  OP([Operator]) -->|bootstrap-tappaas.sh| USB[Proxmox install USB]
  SRC -->|push tag| NIX
  SRC -->|push tag| OPN
  SRC -->|WS0 source-sync| SITE
  USB --> PVE[Proxmox node]
  NIX -->|Release asset| PVE
  OPN -->|Release asset| PVE

1. Proxmox install media

There is no custom Proxmox host image. TAPPaaS installs stock Proxmox VE and layers configuration on top via the cluster foundation module. The only build step is turning the stock ISO into an unattended installer stick.

See docs/design/node-provisioning.md (N2) and the cluster module (src/foundation/cluster/).

2. NixOS template image

The prebuilt, pre-configured NixOS VM template that every foundation/app VM is cloned from.

flowchart LR
  TAG[git tag nixos-template-vX] --> GHA[GitHub Actions ubuntu-latest]
  GHA -->|nix build .#image| QCOW[EFI qcow2]
  QCOW -->|zstd -19| ZST[tappaas-nixos.qcow2.zst]
  ZST -->|action-gh-release| REL[(GitHub Release)]
  REL -->|Create-TAPPaaS-VM.sh: curl + zstd -d| NODE[Proxmox node]
  NODE -->|qm importdisk → tanka1| DISK[imported disk]
  DISK -->|qm template vmid 8080| TPL[VM template]

Consumption happens on the first Proxmox node during foundation install: install-platform.sh (Phase A build_template) calls Create-TAPPaaS-VM.sh, which curls the asset, zstd -ds it, qm importdisks it into the storage pool (tanka1), and qm templates VMID 8080 into a reusable template.

3. OPNsense firewall image

The preconfigured firewall image (issue #231) — the OPNsense analog of the NixOS template.

4. Documentation build

The documentation site is built in a separate repo and published to Codeberg Pages at tappaas.org. It is MkDocs (Material) built by Woodpecker CI; a source-sync step copies allow-listed README.md / INSTALL.md / DESIGN.md files out of this repo into the site at build time, so upstream docs stay canonical here and are never hand-copied.

A push to main here that changes a synced file starts that build: .woodpecker/docs-trigger.yml path-filters the push and asks Woodpecker for a run of the Documentation repo. A push that changes no synced file starts nothing, so there is no cron and no idle load on Codeberg.

The full documentation build — the sync mechanism, the CI pipeline and the Pages hosting — is documented in the Documentation repo:

→ Documentation/BUILD.md