App templates

Ready-made compose templates from the homepage catalog.

The app catalog (Apps → App catalog) offers ready-made Docker Compose templates for well-known apps. A template is only a starting point: the compose file and .env can be edited freely before creating the app, and afterwards the app is an ordinary stack below /appdata/<name>/ like any app created by hand. Your own compose files remain possible at any time through New app.

Where the catalog comes from

The templates are maintained on the homepage and baked into its image with every release. Bunkerbox loads the catalog from the same address as updates (BUNKERBOX_UPDATE_URL, default https://bunkerbox.znbw.de):

Address	Content
GET /api/templates	Index of all templates (id, name, German/English description, category, website, available files)
GET /api/templates/<id>/compose.yaml	Compose file
GET /api/templates/<id>/.env	Example values (optional)
GET /api/templates/<id>/icon.svg or icon.png	Icon (optional)

The index is cached for an hour; Refresh loads it again right away. If the homepage is unreachable, the catalog shows the last loaded state with a notice. Everything that comes from the homepage is checked strictly (names, sizes, file names); icons are delivered through Bunkerbox, so the browser loads nothing directly from other servers.

Creating an app from a template

1. Search the catalog or filter by category and choose Set up.
2. Check the name: the template id is suggested, with -2, -3 etc. when an app of that name exists. The name is also the directory /appdata/<name>/ and the compose project name.
3. Adjust the .env: passwords (all templates contain placeholders such as change-me), paths to your shares (e.g. MEDIA_DIR=/tank/media), the time zone TZ and, for images that support it, PUID/PGID.
4. Optionally change the compose file, then Validate (docker compose config, with the same warnings as for your own apps) and Create app.

When creating, Bunkerbox

• writes docker-compose.yml and .env (mode 600) to /appdata/<name>/,
• creates every relative folder the compose file uses as a bind mount (e.g. ./config, also through variables such as UPLOAD_LOCATION=./library). Newly created folders belong to PUID:PGID from the .env when both are set as numbers (never root); without them they belong to root. Folders are created component by component, symbolic links are never followed. Paths that look like files (e.g. ./config.yml) are not created,
• starts the app with docker compose up when Start after creating is selected.

The app then shows up under Apps and can be edited, updated and deleted like any other.

PUID and PGID

Many images (e.g. those from linuxserver.io) run internally as the user with id PUID and the group PGID. So that the app can access files in your shares, pick the ids of a NAS user or group with access (e.g. id daniel in the terminal). The templates use 1000, which usually is the first user created.

Shipped templates

The list is generated from the meta.json files with node scripts/template-docs.mjs.

Template	Category	Description
Home Assistant (home-assistant)	Smart home	Home automation: devices, sensors and automations in one place, without a cloud. Uses the host network so devices on the LAN are discovered.
Immich (immich)	Photos	Back up and manage photos and videos from your phone, with face recognition and search.
Jellyfin (jellyfin)	Media	Media server for movies, shows and music with apps for TVs, phones and browsers.
Nextcloud (nextcloud)	Cloud	Your own cloud for files, calendars and contacts with desktop and mobile apps.
Paperless-ngx (paperless-ngx)	Documents	Scan documents, make them searchable with OCR and file them automatically.
Syncthing (syncthing)	Synchronisation	Synchronise folders directly between computers and phones, without a cloud service.
Uptime Kuma (uptime-kuma)	Monitoring	Monitors websites, services and devices and reports outages.
Vaultwarden (vaultwarden)	Security	Password manager server compatible with the Bitwarden apps and browser extensions. Needs HTTPS, e.g. through a reverse proxy.

Maintaining templates

Every template is a folder site/templates/<id>/ in the repository (<id>: lowercase letters, digits and -):

File	Required	Content
meta.json	yes	name, description (de, en), category (media, photos, cloud, documents, security, smarthome, monitoring, sync, network, development, other), website (optional), icon (optional)
compose.yaml	yes	Compose file; app data always relative (./config) so it ends up below /appdata/<app>/
.env	no	Example values, TZ and, where the image supports them, PUID/PGID; mark placeholder passwords clearly
icon.svg / icon.png	no	Icon, at most 256 KiB

The tests (test/templates/site.test.ts) check every template (required fields, no absolute paths below /appdata, every variable of the compose file set in the .env, the list above up to date). After adding a template run node scripts/template-docs.mjs. The catalog is published with the next release tag, which rebuilds the homepage image.

Test mode

With BUNKERBOX_MOCK=1 Bunkerbox reads the catalog directly from site/templates/ of the repository. Created apps end up in the simulated Docker, folders are not really created.