Skip to content

Develop a Module — quick start

You have an application; you want it on TAPPaaS. What you build is a module: your app plus a small json contract and a few lifecycle scripts, running in its own VM. In return the platform gives you — without further work — VM provisioning, network zones and firewall rules, a public URL behind the reverse proxy, scheduled updates, backup, and health monitoring.

Before you start

  • A TAPPaaS to develop against. Ideally a test instance; a sufficiently stand-alone module can be developed on a production system — its own VM and, if you want, a dedicated zone keep experiments away from production. See Git & repository topology for the dev-instance setup.
  • Decide where your module will be maintained — the open-source TAPPaaS repo (via pull request), a community repository, or a private one. This shapes your git workflow: Git & repository topology.
  • Know how your app ships. The default module VM is NixOS (configured declaratively in a .nix file); Debian cloud-images, ISO installs and even Windows are supported when your app needs them.

Quick start — template to running VM

Work on the CICD mothership (tappaas-cicd), in its checkout of the source repo:

cd ~/TAPPaaS/src/apps
cp -r 00-Template myapp && cd myapp
mv README-template.md README.md
mv template.json myapp.json        # + template.nix -> myapp.nix, or delete it

The copied scripts are stubs: each warns that it has not been implemented until you replace it. services/myservice/ is a stubbed service — rename it if your module provides one, otherwise delete services/ and the provides entry in myapp.json.

Edit myapp.json — at minimum a free vmid, sizing (cores, memory, diskSize) and the zone (zone0, typically srv), and set stack to what the module is for (the values are listed in module-fields.json). The stack also decides the module's scope (ADR-022e): only the foundation stack is site-scoped (installed in mgmt, official source, --force to delete); every other stack is environment-scoped, which is what an application wants. Then:

module-manager module add myapp

The platform creates the VM, wires its network, and runs your install.sh. README.md documents every file you just copied — the json fields, image/OS choices, providing services, debugging, naming.

Make it run your application

  • install.sh — called once with the module name; puts your software in the VM. For NixOS modules the default install.sh rebuilds the VM from myapp.nix — porting your app is mostly writing that nix configuration.
  • update.sh — called on the platform's update schedule; keeps the app patched without operator attention.
  • test.sh — your regression check; the same tests gate updates.

Iterate and debug

module-manager module test myapp        # run your test.sh
module-manager module reconcile myapp   # re-apply the current config to the VM
module-manager module update myapp      # release update: snapshot + test + merge
module-manager module delete myapp      # --archive by default

Can't SSH in? README.md shows how to take a VM console screenshot through Proxmox — works on any OS, including mid-install.

Going deeper

The module details — every file, field and convention — are in README.md. The contract and machinery behind it:

Ship it

A finished module is a good platform citizen: it updates unattended, its tests pass, its data is backed up, it reports into health, and it carries its own README.md (what it is) and INSTALL.md (what automation can't do for you).

Check it against the blueprint (ADR-027) before you contribute — the same check the release boundary runs on the official repository every fortnight, where a missing required file stops the release:

module-manager validate --blueprint ~/TAPPaaS/src/apps/myapp

A missing required file is an error, a missing test a warning. It never stops an install.

Then contribute it — via pull request to TAPPaaS, a community repository, or keep it private (where modules live). Good first step: open an issue describing the app — someone may already be packaging it. See the contribution guide.