TAPPaaS

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

Quick start — template to running VM

Work on the CICD mothership (tappaas-cicd), in its checkout of the source repo. A module lives in the directory of its stack — src/<stack>/<module>, where <stack> is the stack in its JSON (ai, collaboration, devops, home, security, or misc for one with no natural stack; #421):

cd ~/TAPPaaS/src/home                      # the module's stack
cp -r ../misc/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

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.

Output: Info, Debug and the first install

Your scripts run inside every nightly update of the site, next to thirty other modules. What they print at [Info] is what the operator reads; everything else is noise there. The helpers come from common-install-routines.sh:

Level Use it for Example
info one ✓ line per thing your script established or checked, naming the object info " ${GN}✓${CL} forgejo:repo wired for lazysite: websites/lazysite, read-only deploy key"
install_note where the new module is and how to use it — worth reading once install_note " Site: https://${DOMAIN}"
debug the steps on the way, what already existed, IDs, paths, raw tool output debug " deploy key tappaas-lazysite already in place"
warn / error something the operator must know or act on unchanged

Secrets your module generates

A password, token or key your scripts generate for an instance (a database password, an admin login, an API token) is kept on the mothership as well as in the guest, so a rebuilt guest gets the same one back. It has one place:

What Where
KEY=value secrets /home/tappaas/secrets/<module>/<instance>.env
secrets that are files (a token, a key) /home/tappaas/secrets/<module>/<instance>/

<module> is your module's name and <instance> the instance's (its config/<instance>.json; the same as the module name unless it was installed with --instance). Directories are 0700, files 0600, owned by tappaas. The helpers from common-install-routines.sh create them that way and print the path:

secrets="$(module_secrets_file myapp "${INSTANCE}")"      # .../myapp/<instance>.env
keys="$(module_secrets_dir myapp "${INSTANCE}")"          # .../myapp/<instance>/
grep -q '^DB_PASSWORD=' "${secrets}" || printf 'DB_PASSWORD=%s\n' "$(openssl rand -hex 24)" >> "${secrets}"

Alert rules for your module

Your module can tell the operator by mail when one of its log lines says something went wrong. Put myapp-alerts.json next to myapp.json. You say which lines matter; TAPPaaS builds the log query, limits it to your module's own guests, loads it into the site's Grafana and mails it like every other alert. Your module needs "integratesWith": ["logging:logs"] so its journal is shipped at all.

{
  "rules": [
    {
      "name": "sync-failed",
      "title": "Myapp sync failed",
      "kind": "event",
      "match": "myapp: sync failed",
      "capture": { "account": "account=(?P<account>[a-z0-9-]+)" },
      "window": 300,
      "summary": "A sync run failed. The account is named in the subject; the next run retries it."
    },
    {
      "name": "worker-silent",
      "title": "Myapp worker stopped",
      "kind": "state",
      "unit": "myapp-worker\\.service",
      "match": "heartbeat",
      "absent": true,
      "window": 900,
      "summary": "The worker has not logged its heartbeat for 15 minutes.",
      "mail": { "subject": "{state}: {title} on {host}" }
    }
  ]
}
Field Meaning
name short DNS-style name, unique in the file
title the alert's name in the mail subject (plain ASCII); headline overrides it in the subject
kind event — something happened, mailed once; state — something is so, mailed again when it clears
match a regular expression (RE2) a log line must match
unit optional: only lines of systemd units matching this expression
capture optional: up to 3 labels taken from the line, each an expression with a named group of the label's name; one alert per value
window seconds the rule looks back, 60–86400
above optional: fire only when more than this many lines matched in the window
absent optional: fire when no line matched in the window (a heartbeat that stopped)
repeat optional: how often a firing alert is mailed again, 1h–24h (default 4 h)
security optional: info, warning or critical — the rule is a security hit (ADR-050). Each hit is kept per rule and machine with its count; a warning holds its threat condition 24 h from the last hit, a critical until someone acknowledges it (health-manager ack <ci> --type threat --note …), and info raises nothing. Rendered only while the site's security monitoring is on (site.json security.monitoring; off on a small site)
summary the explanation in the mail
mail optional: your own subject and body, with {state}, {title}, {host}, {hosts}, {module}, {labels}, {label.<name>}, {summary}, {since}, {resolved}, {query}, {lines}
include optional: "bundle" attaches the site's support bundle; "lines" adds up to 20 matching log lines

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/home/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.