App-Vorlagen

Fertige Compose-Vorlagen aus dem Katalog der Homepage.

Der App-Katalog (Apps → App-Katalog) bietet fertige Docker-Compose-Vorlagen für bekannte Apps. Eine Vorlage ist nur ein Startpunkt: Compose-Datei und .env lassen sich vor dem Anlegen frei bearbeiten, und danach ist die App ein ganz normaler Stack unter /appdata/<name>/ wie jede von Hand angelegte. Eigene Compose-Dateien sind weiterhin jederzeit über Neue App möglich.

Herkunft des Katalogs

Die Vorlagen werden auf der Homepage gepflegt und mit jedem Release in deren Image eingebaut. Bunkerbox lädt den Katalog von derselben Adresse wie die Updates (BUNKERBOX_UPDATE_URL, Standard https://bunkerbox.znbw.de):

Adresse	Inhalt
GET /api/templates	Verzeichnis aller Vorlagen (id, Name, Beschreibung Deutsch/Englisch, Kategorie, Webseite, vorhandene Dateien)
GET /api/templates/<id>/compose.yaml	Compose-Datei
GET /api/templates/<id>/.env	Beispielwerte (optional)
GET /api/templates/<id>/icon.svg bzw. icon.png	Symbol (optional)

Das Verzeichnis wird eine Stunde zwischengespeichert; Aktualisieren lädt es sofort neu. Ist die Homepage nicht erreichbar, zeigt der Katalog den zuletzt geladenen Stand mit einem Hinweis. Alles, was von der Homepage kommt, wird streng geprüft (Namen, Größen, Dateinamen); Symbole werden über Bunkerbox ausgeliefert, der Browser lädt nichts direkt von fremden Servern.

App aus einer Vorlage anlegen

1. Im Katalog eine Vorlage suchen oder nach Kategorie filtern und Einrichten wählen.
2. Name prüfen: vorgeschlagen wird die Kennung der Vorlage, bei einer schon vorhandenen App mit -2, -3 usw. Der Name ist zugleich das Verzeichnis /appdata/<name>/ und der Compose-Projektname.
3. .env anpassen: Passwörter (alle Vorlagen enthalten Platzhalter wie change-me), Pfade zu deinen Freigaben (z. B. MEDIA_DIR=/tank/media), Zeitzone TZ, und bei Images, die das unterstützen, PUID/PGID.
4. Optional die Compose-Datei ändern, dann Prüfen (docker compose config, mit denselben Warnungen wie bei eigenen Apps) und App anlegen.

Beim Anlegen:

• schreibt Bunkerbox docker-compose.yml und .env (Rechte 600) nach /appdata/<name>/,
• legt alle relativen Ordner an, die die Compose-Datei als Bind-Mount verwendet (z. B. ./config, auch über Variablen wie UPLOAD_LOCATION=./library). Neu angelegte Ordner gehören PUID:PGID aus der .env, wenn beide als Zahl gesetzt sind (nie root); ohne diese Werte gehören sie root. Ordner werden Komponente für Komponente angelegt, symbolische Links werden nie verfolgt. Pfade, die wie Dateien aussehen (z. B. ./config.yml), werden nicht angelegt,
• startet die App mit docker compose up, wenn Nach dem Anlegen starten gewählt ist.

Danach erscheint die App unter Apps und lässt sich wie jede andere bearbeiten, aktualisieren und löschen.

PUID und PGID

Viele Images (z. B. die von linuxserver.io) laufen intern als der Benutzer mit der Kennung PUID und der Gruppe PGID. Damit die App auf Dateien in deinen Freigaben zugreifen kann, wähle die Kennungen eines NAS-Benutzers bzw. einer Gruppe mit Zugriff (z. B. id daniel im Terminal). Die Vorlagen verwenden 1000, was meist der erste angelegte Benutzer ist.

Mitgelieferte Vorlagen

Die Liste wird mit node scripts/template-docs.mjs aus den meta.json-Dateien erzeugt.

Vorlage	Kategorie	Beschreibung
Home Assistant (home-assistant)	Smart Home	Hausautomation: Geräte, Sensoren und Automationen an einem Ort, ohne Cloud. Nutzt das Host-Netzwerk, damit Geräte im LAN gefunden werden.
Immich (immich)	Fotos	Fotos und Videos vom Smartphone sichern und verwalten, mit Gesichtserkennung und Suche.
Jellyfin (jellyfin)	Medien	Medienserver für Filme, Serien und Musik mit Apps für Fernseher, Smartphone und Browser.
Nextcloud (nextcloud)	Cloud	Eigene Cloud für Dateien, Kalender und Kontakte mit Desktop- und Smartphone-Apps.
Paperless-ngx (paperless-ngx)	Dokumente	Dokumente scannen, per Texterkennung durchsuchbar machen und automatisch ablegen.
Syncthing (syncthing)	Synchronisation	Ordner zwischen Rechnern und Smartphones direkt synchronisieren, ohne Cloud-Dienst.
Uptime Kuma (uptime-kuma)	Überwachung	Überwacht Webseiten, Dienste und Geräte und meldet Ausfälle.
Vaultwarden (vaultwarden)	Sicherheit	Passwort-Manager-Server, kompatibel mit den Bitwarden-Apps und -Browsererweiterungen. Braucht HTTPS, z. B. über einen Reverse-Proxy.

Vorlagen pflegen

Jede Vorlage ist ein Ordner site/templates/<id>/ im Repository (<id>: Kleinbuchstaben, Ziffern und -):

Datei	Pflicht	Inhalt
meta.json	ja	name, description (de, en), category (media, photos, cloud, documents, security, smarthome, monitoring, sync, network, development, other), website (optional), icon (optional)
compose.yaml	ja	Compose-Datei; Daten der App immer relativ (./config), damit sie unter /appdata/<app>/ landen
.env	nein	Beispielwerte, TZ und – wo das Image sie unterstützt – PUID/PGID; Platzhalter-Passwörter deutlich kennzeichnen
icon.svg / icon.png	nein	Symbol, höchstens 256 KiB

Die Tests (test/templates/site.test.ts) prüfen jede Vorlage (Pflichtfelder, keine absoluten Pfade unter /appdata, jede Variable der Compose-Datei in der .env gesetzt, die Liste oben aktuell). Nach dem Hinzufügen einer Vorlage node scripts/template-docs.mjs ausführen. Veröffentlicht wird der Katalog mit dem nächsten Release-Tag, das das Image der Homepage neu baut.

Testmodus

Mit BUNKERBOX_MOCK=1 liest Bunkerbox den Katalog direkt aus site/templates/ des Repositorys. Angelegte Apps landen im simulierten Docker, Ordner werden nicht wirklich angelegt.