Apps that FHS devices install and update. Glossary: CONTEXT.md.
catalog.json # apps shown in the store (name, tagline, icon, ...)
<app>/
manifest.json # releases, appended by `mise run release`; authors edit appPort only
latest/ # working copy: the only folder authors edit
release.json # {"appVersion": "v3.3.1", "canSkip": true, "healthTimeoutMinutes": 60}
docker-compose.yml # stock compose, close to upstream's
settings.json # deployment choices and the compose changes they make
health-check.sh # exit 0 = serving
data/ # seed folders copied into the app's data on install (.gitkeep dropped)
releases/<n>/ # frozen copy of latest/ made by `mise run release`; never edited
_template/ # starting point for a new app
scripts/ # bash tooling, run with `mise run <task>`
- A PR that changes
<app>/latest/also adds its release: runmise run release <app>, which copieslatest/toreleases/<n+1>/and appends{version, appVersion, canSkip}to the manifest. Run it again after every change; it rebuilds the PR's release, so a PR adds exactly one. CI rejects alatest/that differs from the newest release, and a PR that adds more than one release. On a conflict inreleases/ormanifest.json, take master's side and run it again. versionis the release number (1, 2, 3, ...); updates follow it.appVersionis the upstream version, shown to users only; a manifest entry's must match its release'srelease.json.canSkip: falsemakes the release a required stop: every update lands on it and passes its health check before going further. Once merged, the only allowed change iscanSkipfromfalsetotrueinmanifest.json.healthTimeoutMinutes(optional, 1 to 360, default 30) is how long the health gate waits for this release to pass its health check. Set it from the timesci-runprints (healthy after N s) with a clear margin: longer for a slow migration, shorter for an app that can get stuck, so the user isn't kept waiting for a start that won't finish.- Merged releases and folders never change; to fix a release, add a new one.
Only deployment choices that change the compose belong here (a folder to mount, hardware acceleration). Anything configured inside the app is set in the app itself. Every setting has a default.
| Type | Value | compose |
|---|---|---|
path |
a folder the user picks from indexed external locations; unset = app data | a fragment, applied when a folder is picked |
enum |
one of options[].value |
map option value → fragment |
bool |
true / false |
map "true"/"false" → fragment |
A secret the app needs is ${APP_SEED} or ${APP_PASSWORD}: derived on the device per
app, the same on every render, never shown or stored.
Field keys: key (UPPER_SNAKE, also the env var name; APP_, FHS_, COMPOSE_
reserved), type, label, optional help, editable (default true; false = chosen
at install only), default (required for enum and bool), options (enum).
Fragments merge into the stock compose with compose's own rules (docker compose -f stock -f fragment config): they add and override; a volume with the same target replaces the
stock one. path fragments must bind with long syntax and
"bind": {"create_host_path": false}, so a missing drive fails the start instead of
filling the system disk. CI loads every rendered combination like a device does and
rejects one that doesn't load.
A release keeps every path setting of the release before it, as a path: dropping or
renaming one would move users' data back to app data on update, so CI rejects it.
- Values reach the compose as
${KEY}(a bool astrueorfalse, an unset folder as empty), plus platform variablesAPP_ID,APP_DATA_DIR,APP_SEED,APP_PASSWORDandAPP_TZ(the device's time zone, likeAmerica/Chicago). Data lives under${APP_DATA_DIR}; named and anonymous volumes, relative binds,env_file,container_name(names are global on the host), floating tags and SELinux:z/:Zare rejected, in the stock compose and every fragment. Any other${NAME}would render empty, so CI rejects it ($$for a literal$). - Bind every path an image declares as
VOLUMEunder${APP_DATA_DIR}, or docker makes an anonymous volume that the snapshot misses and everydownleaves behind.ci-runfails on one. - Every service sets
restart: alwaysorrestart: unless-stopped. - The stock compose publishes the app's
appPortover tcp, and no two apps publish the same host port. Within one settings combination, no two services publish the same host port and protocol on overlapping addresses. An app onnetwork_mode: hostis taken to use itsappPort; other ports it opens aren't checked. health-check.shruns asbash -euo pipefailfrom the release folder, 5 s per run, as root, with onlyPATH=/usr/bin:/usr/sbin,HOME,LANG=C.UTF-8,APP_ID,APP_DATA_DIRandAPP_TZset: no secrets, no setting values. It can use bash, coreutils, grep, sed, gawk, jq and curl, nothing else. No docker.- A failing
health-check.shsays why in one or two plain lines a user or support can act on: what it asked and what it got (the URL and status code, still installing, in maintenance mode). The device shows the last 20 lines it printed when the health gate gives up, so a silent check leaves the user with nothing. A passing one prints nothing.ci-runfails on either. catalog.jsonicons are absolutehttpsURLs, and every app is incatalog.json.
mise run new-app <app-id> <port>(copies_template/).- Fill in
<app>/latest/and add acatalog.jsonentry. mise run release <app>andmise run validate, then open a PR. CI also installslatest/and, from the second release on, updates from the previous release to the new one (mise run ci-run).
mise pins shellcheck, shfmt, oras, cosign and crane (mise install) and runs every command. The scripts are bash and need
jq and docker on the host, like the device. scripts/generate-compose.sh is the only renderer: the
agent runs it on the device, CI runs it here. CI pins docker compose to the version the OS
image ships, since the merge rules are compose's.
scripts/
validate-store.sh, generate-compose.sh, new-app.sh, release.sh, ci-run.sh,
pack-store.sh, publish-store.sh, check-images.sh commands
*.test.sh their tests
mise run validate: strict checks and a render of every settings combination (needs docker;SKIP_RENDER=1skips renders and the compose and port rules checked on them,BASE_REF=<ref>checks published history).mise run generate-compose <release-dir> <app-id> [user_settings.json]: the compose a device would run, on stdout. NeedsAPP_DATA_DIR,APP_SEED,APP_PASSWORDandAPP_TZin the environment. A stored value the release doesn't accept exits 10, its key on stdout and the reason on stderr; any other failure exits non zero with the reason.mise run ci-run install|update <app-id>: runs the app like a device (pulls images).mise run release <app-id>: freezeslatest/into the PR's release (BASE_REF, defaultorigin/master, is the branch the PR merges into).mise run pack <out>: the store bundle devices download, the same bytes for the same store. Fails over the agent's limits: 1 MiB packed, 64 MiB unpacked.mise run publish commit: what CI runs onmasteroncevalidatepasses. Pushesstore:<commit>to ghcr, signs it, copies it and its signature to oci.futo.org, then movesnightlyandalphaon each, only forward. Its revision is the last commit onmaster's first parent line that changed the store or how it's packed, so the same store always gets the same digest, and a channel moves only when the commit it points at is an ancestor of that one.mise run publish pr <number>pushes a PR's unsignedstore:pr-<number>to ghcr.STORE_REPOSITORIESpoints it at other registries,COSIGN_KEYsigns with a key instead of CI's keyless identity.mise run check-images: what CI runs every night. Every image of every published release, rendered with the defaults, each enum and bool choice and each folder set, must resolve and mount eachVOLUMEit declares.mise run test: the tooling's tests (need docker).mise run lint: shfmt format check and shellcheck (lint-fixformats).