Skip to main content

Templates for developers

Every app in the Obacht store is a template: one YAML file that says which image to run, which settings to ask for and which port to put a web address on. You can write one for any open source app that runs in a container, and submit it as a community template.

What a template is​

A template is a manifest in the format obacht.dev/v2. It describes the result, never the steps. There is no install script, no shell, no "run this after". The agent on the device reads the manifest and builds everything from it: the containers, the volumes, the generated passwords, and the route from the web address to your app.

That keeps templates small. Uptime Kuma is 70 lines, Ghost with its MySQL database about 130. Most of that is description and settings.

The path from your repo to a device​

  1. You write manifest.yml against the spec.
  2. You submit it on registry.obacht.dev/contribute.
  3. We review it, install it on a Raspberry Pi, a Linux PC and a Mac, and give feedback in the submission.
  4. When it is accepted, the registry pins the images of a bundle to their exact digests and signs the manifest.
  5. The template shows up in the store. When someone installs it, their device checks the registry signature before it pulls anything, and refuses a bundle image that does not match its pinned digest.

Only Obacht can sign. That is the point: a device runs a template only when the manifest is the one that was reviewed.

Community templates​

Templates carry a trust level, and the store shows it on every card.

In the storeWhat it means
OfficialBuilt and maintained by Obacht.
Community (Reviewed)Written by someone else, reviewed and tested by Obacht.
ExperimentalWritten by someone else, accepted but not fully reviewed. Use at your own risk.

A new community template starts as Experimental and moves to Community (Reviewed) once we have tested it in depth. Community templates start with the public launch: from then on accepted ones appear in the store. The form is open now, so you can submit early and we review what comes in.

Some things stay official only. Templates that run outside Docker, directly on the Raspberry Pi (the system runtime, used for the kiosk and the camera), are rejected on the community path.

What you need to know​

  • Docker. If your app has a working docker run or docker compose setup, you have most of a template.
  • Images for two architectures. linux/arm64 covers the Raspberry Pi and the Mac, linux/amd64 the Linux PC. Most official images on Docker Hub and GHCR ship both.
  • What a non-technical user can decide. Every setting you add is a question in the install sheet. Ask little.

In this section​

The spec itself, with the JSON Schema and the authoring guide, is public on GitHub: obacht-dev/obacht-template-spec.