TrueNAS App Catalog: eigene Docker-Images bereitstellen

Mit TrueNAS Scale 25.04 (“Fangtooth”) hat iXsystems den App Catalog grundlegend modernisiert. Statt der bisherigen Kubernetes-Schicht setzt das System jetzt auf Docker Compose als Laufzeit — schlanker, deutlich schneller im Start und vor allem kompatibel mit nahezu jedem Compose-File aus dem Internet. Für Administratoren in kleinen und mittleren Unternehmen bedeutet das: Das NAS wird zur ernsthaften Plattform für eigene Container-Workloads, ohne dass ein separater Docker-Host oder ein Proxmox-LXC dafür nötig ist.

In diesem Artikel zeigen wir, wie Sie über die “Custom App”-Funktion eigene Docker-Images aus einer privaten Registry oder vom Docker Hub bereitstellen, wie persistente Daten sauber in TrueNAS-Datasets landen und welcher Update-Workflow sich in der Praxis bewährt.

Was die Custom App in TrueNAS Scale leistet

Der offizielle App Catalog enthält geprüfte Anwendungen wie Nextcloud, Plex, Immich oder Vaultwarden. Für alles, was nicht im Katalog liegt, existiert in der Apps-Oberfläche der Eintrag “Custom App”. Dieser akzeptiert ein vollständiges Docker-Compose-YAML und übernimmt die gesamte Orchestrierung — inklusive automatischem Start nach Reboot, Health-Checks und Log-Einsicht direkt im Web-UI.

Im Hintergrund läuft ein dedizierter Docker-Daemon mit eigenem Storage-Pool. Anders als bei einer manuellen Docker-Installation auf TrueNAS Core früher wird die Konfiguration vollständig vom System verwaltet. Updates des Betriebssystems überschreiben Ihre Container also nicht mehr, und ein “apps” — Pool sorgt für saubere Trennung von NAS-Daten und Container-Metadaten.

Zu beachten ist: Die Custom App ist keine reine Compose-Datei, sondern eine leicht erweiterte Variante. Netzwerke und einige TrueNAS-spezifische Felder werden vom System automatisch ergänzt, wenn Sie das nicht selbst tun. Das vereinfacht Standardfälle, kann aber bei sehr komplexen Stacks verwirren.

Vorbereitung: Pool, Dataset, Netzwerk

Bevor die erste Custom App deployt wird, sollte die Storage-Struktur stehen. Wir empfehlen folgendes Schema, das sich bei TrueNAS-Projekten in der Praxis als robust erwiesen hat:

Dataset	Zweck	Empfohlene Eigenschaften
tank/apps	Docker-Root, Image-Layer	recordsize 128K, compression LZ4
tank/appdata/<app>/config	Konfigurationsdateien	recordsize 16K, snapshots stündlich
tank/appdata/<app>/data	Nutzdaten, Datenbanken	recordsize 64K, snapshots täglich
tank/media	Read-Only-Quelle z. B. für Mediaserver	shared mit SMB/NFS

Der eigentliche Apps-Pool wird unter “Apps — Configuration” einmalig ausgewählt. Danach sollten Sie für jede Anwendung ein eigenes Dataset unterhalb von appdata anlegen — so funktionieren Snapshots und Replikation pro App, was bei einem Rollback Gold wert ist.

Für die Netzwerk-Seite reicht in den meisten SMB-Setups die Standard-Bridge. Wer mehrere VLANs auf dem TrueNAS hat, kann zusätzlich Macvlan-Netze definieren, um Container direkt mit eigener IP ins Management- oder DMZ-Netz zu hängen — praktisch in Kombination mit einer sauber segmentierten OPNsense.

Eigenes Image aus privater Registry einbinden

Die spannendste Frage in der Praxis ist die Quelle des Images. Drei Szenarien sind typisch:

1. Öffentliches Image von Docker Hub oder GHCR — trivial.
2. Privates Image in einer self-hosted Registry (z. B. Harbor, Gitea, distribution/registry).
3. Eigene Builds, die per CI nach jedem Commit gepusht werden.

Für die private Registry hinterlegen Sie unter “Apps — Discover Apps — Manage Container Images — Pull Image” einmalig Hostname, Benutzer und Token. Diese Credentials werden verschlüsselt im System abgelegt und beim Pull automatisch verwendet. Damit landet ein Image z. B. von registry.firma.lan:5000/intern/zeiterfassung:2.4.1 ohne weitere Handgriffe auf dem NAS.

Ein minimaler Custom-App-Eintrag für eine eigene Webanwendung mit PostgreSQL-Backend sieht so aus:

services:
  app:
    image: registry.firma.lan:5000/intern/zeiterfassung:2.4.1
    restart: unless-stopped
    environment:
      - DATABASE_URL=postgres://app:${DB_PASSWORD}@db:5432/app
      - TZ=Europe/Berlin
    ports:
      - "8080:8080"
    volumes:
      - /mnt/tank/appdata/zeiterfassung/config:/app/config
      - /mnt/tank/appdata/zeiterfassung/uploads:/app/uploads
    depends_on:
      - db
  db:
    image: postgres:17-alpine
    restart: unless-stopped
    environment:
      - POSTGRES_USER=app
      - POSTGRES_DB=app
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    volumes:
      - /mnt/tank/appdata/zeiterfassung/db:/var/lib/postgresql/data

Wichtig: Die Host-Pfade müssen vorab als Dataset existieren. TrueNAS legt zwar Verzeichnisse on-the-fly an, aber dann landet alles auf dem Root-Dataset des Pools und nicht in einem eigenen ZFS-Dataset — Snapshots wären damit nutzlos.

Ports, Reverse Proxy und TLS

Direkt freigegebene Ports wie 8080:8080 sind für interne Tests okay, in Produktion sollte aber konsequent ein Reverse Proxy davor stehen. Bewährt hat sich Traefik oder Caddy als zweite Custom App, die auf 80/443 lauscht und per Docker-Label die anderen Container automatisch findet.

Damit ergeben sich saubere Hostnamen wie zeiterfassung.firma.lan, TLS-Zertifikate kommen entweder aus dem internen ACME-Server der OPNsense oder von Let’s Encrypt per DNS-Challenge. Der Container selbst muss dafür gar keinen Port mehr auf den Host exponieren — nur das interne Docker-Netz wird verwendet, was die Angriffsfläche reduziert.

Wer keinen eigenen Reverse Proxy betreiben möchte, kann die TrueNAS-eigene “Custom Apps — Network — Host Networking”-Option setzen. Damit teilt sich der Container den Host-Stack und kann auch privilegierte Ports nutzen. Für Datenbanken oder LDAP-Bridges ist das oft die einfachste Variante.

Update-Workflow in der Praxis

Das Image-Tag ist der zentrale Hebel für Updates. Wir empfehlen, in Custom Apps nie das Tag latest zu verwenden, sondern immer eine konkrete Version. Das macht Rollbacks reproduzierbar und verhindert ungewollte Major-Upgrades, wenn der Pool nachts gepullt wird.

Der typische Update-Lauf sieht so aus:

1. CI baut neues Image, pusht als :2.4.2 in die Registry.
2. Snapshot des appdata-Datasets anlegen (manuell oder per Snapshot-Task).
3. Im TrueNAS-UI die Custom App editieren, Tag auf :2.4.2 heben, “Save”.
4. TrueNAS zieht das Image, ersetzt den Container, startet automatisch neu.
5. Bei Problemen: Tag zurückstellen, Dataset auf den Snapshot zurückrollen.

Für mehrere Apps lohnt sich ein kleines Script, das per midclt (die TrueNAS-CLI-API) die Image-Tags massenhaft aktualisiert. So entsteht ein “GitOps-light”-Ansatz, der besonders gut zu Setups passt, in denen Backup und Replikation per ZFS sowieso schon automatisiert sind.

Grenzen und Empfehlungen

Die Custom App ist mächtig, aber nicht für jeden Workload die richtige Wahl. Wenn Sie HA, Live-Migration oder mehrere Knoten brauchen, ist ein Proxmox-Cluster mit dedizierten VMs die bessere Plattform. Auch sehr ressourcenhungrige Datenbanken oder eine produktive Kubernetes-Plattform gehören nicht auf das NAS. Für interne Tools, Dashboards, Monitoring-Stacks, Dokumenten-Workflows und kleine Webanwendungen ist die Custom App dagegen ideal — der Storage liegt eh schon dort, ZFS-Snapshots schützen die Daten, und die Bedienung bleibt vollständig im TrueNAS-UI.

Ein Wort zur Sicherheit: Container im selben Docker-Netz können einander erreichen. Wer Mandanten trennt, sollte mehrere Docker-Netze definieren oder die kritischen Anwendungen auf einen separaten TrueNAS-Knoten ziehen.

DATAZONE unterstützt Sie

Wir planen und betreiben TrueNAS-Scale-Umgebungen für mittelständische Unternehmen in Bayern — von der Dataset-Struktur über die Custom-App-Architektur bis zur Anbindung an eine private Container-Registry. Wenn Sie eigene Docker-Workloads sauber auf dem NAS betreiben möchten, ohne sich in YAML zu verlieren, sprechen Sie uns gerne an: Kontakt aufnehmen.