Skip to content

Deployment mit Docker und rootless Podman ​

Zielarchitektur ​

text
Browser
   │
   ▼
ytmdl-frontend        Nginx Alpine
   │  /       → statisches Webfrontend
   │  /api/*  → backend:8080
   ▼
ytmdl-backend         Go-Backend, REST API, SSE, Job Queue, Worker,
   │                  yt-dlp, ffmpeg, ffprobe
   ▼
ytmdl-db              PostgreSQL 18 (postgres:18-alpine)

Alle drei Container liegen im dedizierten Bridge-Netz ytmdl-net und sprechen sich ausschließlich über ihre Compose-Service-Namen (db, backend, frontend) an — nie über IP-Adressen. Nach außen ist ausschließlich Port 8080 am Frontend veröffentlicht.

Der Worker ist Teil desselben Go-Prozesses wie die API; es gibt bewusst keinen eigenen Worker-Container und keine zusätzliche Queue-Infrastruktur.

Das Backend-Image besteht aus einem Go-Builder auf golang:alpine und einem separaten Alpine-Runtime-Image. Die Runtime enthält nur die statische Backend-Binary sowie yt-dlp, ffmpeg, ffprobe und CA-Zertifikate — keinen Go-Compiler. Der Backend-Prozess und alle gestarteten Werkzeuge laufen als UID/GID 10001, nicht als root.

/app und die Binary bleiben root-owned und für den Dienstbenutzer nur les-/ausführbar. Flüchtige Tool-Caches liegen unter /tmp/musicdl; persistent beschreibbar sind ausschließlich /data und /music. Der Katalog liegt vollständig in PostgreSQL.

Voraussetzungen ​

  • Podman 5 oder neuer, rootless (oder Docker Compose V2)
  • Ein Compose-Provider: Empfohlen wird der native Compose V2-Provider (podman-compose-subcommand / Docker Compose Plugin).

    NOTE

    Die Python-Implementierung podman-compose (Version 1.3.x oder älter) ist mit den Compose v2-Optionen und User-Namespace-Mappings (keep-id) von YTMDL teilweise inkompatibel. Der Host-Updater ytmdlctl erkennt diesen Provider im Preflight und blockiert Änderungen zum Schutz der Installation.

  • Ausgehende Netzverbindung für die Provider-APIs und die Downloads

Installation der offiziellen Images ​

Der geprüfte Einstieg ist das versionierte Paket aus dem v1.6.0 Release. Die Schnellstartanleitung beschreibt Download, Prüfsumme und python3 scripts/install.py --engine docker beziehungsweise --engine podman. Der Installer bereitet ausschließlich neue Verzeichnisse vor. Vorhandene Installationen werden mit dem verifizierten v1-CLI aktualisiert.

Manuelle Befehle für die offiziellen Images wählen die Dateien ausdrücklich:

sh
docker compose -f compose.ghcr.yaml ps
podman compose -f compose.ghcr.yaml -f compose.ghcr.podman.yaml ps

compose.ghcr.podman.yaml ergänzt ausschließlich das rootless UID-Mapping. Host-spezifische Overrides werden als letzte Datei angegeben. ytmdlctl wählt beide Dateien bei Podman und vorhandene Host-Overrides automatisch.

Compose startet zuerst ytmdl-db, wartet auf dessen Healthcheck und startet danach ytmdl-backend. Zusätzlich wartet das Backend beim Start selbst noch bis zu MUSICDL_DB_STARTUP_TIMEOUT (Standard 90s) mit exponentiellem Backoff auf die Datenbank. depends_on ist also nur eine Beschleunigung — die Anwendung verlässt sich nicht darauf und startet auch dann korrekt, wenn die Datenbank erst Sekunden später bereit ist.

Netzwerk ​

yaml
networks:
  ytmdl-net:
    name: ytmdl-net
    driver: bridge
    ipam:
      config:
        - subnet: 172.31.250.0/28
EigenschaftWert
Nameytmdl-net
Treiberbridge
Subnetz172.31.250.0/28 (16 Adressen, Gateway 172.31.250.1)
internalnein

Ein /28 reicht für diesen Stack und reserviert nicht unnötig ein ganzes /24. Das Netz ist bewusst nicht internal: true: das Backend braucht ausgehenden HTTPS-Zugriff für YouTube, YouTube Music, die Spotify-API, yt-dlp und die Cover-Downloads.

Container erhalten ihre Adressen dynamisch aus diesem Subnetz. Es sind keine statischen IPs konfiguriert, und keine Konfiguration verweist auf eine IP-Adresse — die Auflösung läuft über die Service-Namen:

sh
podman exec ytmdl-backend getent hosts db
# 172.31.250.2   db.dns.podman  db.dns.podman db

Subnetz-Kollision ​

172.31.250.0/28 liegt in einem privaten RFC1918-Bereich und kann theoretisch mit einem vorhandenen LAN-, VPN- oder anderen Container-Netz kollidieren. Falls das passiert, kann für den offiziellen Stack YTMDL_NETWORK_SUBNET in .env auf ein freies Subnetz gesetzt werden. Es ist keine Anpassung an anderer Stelle nötig, weil die Container über DNS-Service-Namen und nicht über fest codierte IP-Adressen kommunizieren. Eine automatische Netzwerkerkennung gibt es bewusst nicht.

Ports ​

ContainerHost-PortBegründung
ytmdl-frontend8080:8080Webfrontend & API-Reverse-Proxy
ytmdl-backend—nur über ytmdl-net erreichbar
ytmdl-db—nur über ytmdl-net erreichbar

PostgreSQL und Backend veröffentlichen bewusst keinen direkten Host-Port. Der Frontend-Nginx nimmt Anfragen entgegen, liefert statische Assets aus und leitet /api/* über ytmdl-net an backend:8080 weiter.

Environment ​

Alle Werte kommen aus .env. Secrets gehören ausschließlich dorthin; .env.example enthält nur Beispielwerte und .env ist von Git ausgeschlossen.

Die Backend-Variablen behalten das Präfix MUSICDL_*; das ist der bestehende, getestete Vertrag des Backends und wurde nicht aus kosmetischen Gründen auf YTMDL_* umbenannt. YTMDL_* benennt nur die reinen Compose-/Build-Werte.

VariableBedeutung
POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORDInitialisierung von ytmdl-db
MUSICDL_DATABASE_URLVerbindungs-URL des Backends, z. B. postgres://ytmdl:pw@db:5432/ytmdl?sslmode=disable
MUSICDL_LISTEN_ADDRHTTP-Listener, Standard 0.0.0.0:8080
MUSICDL_LIBRARYBibliothekspfad im Container, Standard /music
MUSICDL_CONCURRENT_DOWNLOADSParallel verarbeitete Tracks
MUSICDL_YTDLP, MUSICDL_FFMPEG, MUSICDL_FFPROBEPfade der Werkzeuge
MUSICDL_DB_MAX_CONNS, MUSICDL_DB_MIN_CONNSGrenzen des Connection Pools (Standard 10/2)
MUSICDL_DB_MAX_CONN_LIFETIME, MUSICDL_DB_MAX_CONN_IDLE_TIMELebensdauer und Leerlauf einer Verbindung (Standard 30m/5m)
MUSICDL_DB_CONNECT_TIMEOUTTimeout eines einzelnen Verbindungsversuchs (Standard 10s)
MUSICDL_DB_STARTUP_TIMEOUT, MUSICDL_DB_STARTUP_BACKOFFGesamtbudget und erster Backoff beim Warten auf PostgreSQL
MUSICDL_DEEZER_REQUESTS_PER_SECOND, MUSICDL_DEEZER_BURSTDeezer-Drosselung (Standard 8/s, Burst 5)
MUSICDL_DEEZER_MAX_RETRIES, MUSICDL_DEEZER_RETRY_BACKOFF, MUSICDL_DEEZER_MAX_RETRY_BACKOFFDeezer-Retry-Grenzen (Standard 3, 500ms, 8s)
MUSICDL_SUBSCRIPTIONS_ENABLED, MUSICDL_SUBSCRIPTION_SYNC_INTERVALKünstler-Abonnements und Sync-Intervall (Standard true, 24h)
MUSICDL_SUBSCRIPTION_CHECK_INTERVAL, MUSICDL_SUBSCRIPTION_RETRY_INTERVALScheduler-Prüfintervall und Retry-Intervall (Standard 15m, 1h)
MUSICDL_SUBSCRIPTION_SYNC_TIMEOUT, MUSICDL_SUBSCRIPTION_BATCH_SIZESync-Timeout und Batch-Größe (Standard 30m, 25)
YTDM_SPOTIFY_CLIENT_ID, YTDM_SPOTIFY_CLIENT_SECRETOptionaler Spotify-Metadatenprovider
YTDM_COOKIEFILEOptionale cookies.txt, z. B. /data/cookies.txt
YTMDL_VERSION, YTMDL_HOST_PORT, YTMDL_DATA_PATH, YTMDL_MUSIC_PATHnur von Compose gelesen

Das Backend loggt die Verbindungs-URL nur ohne Passwort und schreibt Credentials in keine Log- oder Fehlermeldung.

Die alten Variablen MUSICDL_DATABASE und YTDM_DATABASE_PATH zeigten auf eine SQLite-Datei. Sie werden bewusst nicht mehr ignoriert, sondern führen zu einem klaren Startfehler mit dem Hinweis auf MUSICDL_DATABASE_URL.

Volumes ​

ZielInhaltTyp
ytmdl-postgres-data → /var/lib/postgresqlPostgreSQL-ClusterNamed Volume
./music → /musicMusikbibliothekBind-Mount
./data → /dataoptionale Laufzeitdateien wie cookies.txtBind-Mount

Es liegt kein PostgreSQL-Datenverzeichnis im Projektrepository; der Cluster lebt ausschließlich im Named Volume.

Das Image postgres:18-alpine legt seinen Cluster unter $PGDATA=/var/lib/postgresql/18/docker an und deklariert sein Volume eine Ebene darüber. Ein Mount auf das ältere /var/lib/postgresql/data lässt das Image mit einer ausführlichen Fehlermeldung abbrechen; der Mount muss deshalb auf /var/lib/postgresql liegen.

Rootless Podman und Bind-Mounts ​

Die gemeinsame compose.ghcr.yaml funktioniert mit Docker. Podman ergänzt compose.ghcr.podman.yaml mit keep-id:uid=10001,gid=10001, sodass der rootless Container-Benutzer dem Backend-Benutzer entspricht. Der frische Installer bereitet nur die neuen Verzeichnisse und den Guard-Marker vor und prüft Schreibzugriff als Dienstbenutzer. Bestehende Daten werden nicht rekursiv umgeschrieben.

ytmdl-db braucht kein keep-id: sein Cluster liegt in einem Named Volume, dessen Eigentümer Podman im Benutzer-Namespace verwaltet. Für vorhandene NAS-Mounts gelten die Storage-Anleitungen. Prüfe Rechte und Marker im tatsächlichen Container-Mount, bevor du ein Update startest.

Healthchecks ​

sh
podman compose -f compose.ghcr.yaml -f compose.ghcr.podman.yaml ps
curl -fsS 'http://127.0.0.1:8080/api/v1/health?scope=essential'

ytmdl-db prüft sich mit pg_isready. Der Containercheck des Backends mit scope=essential prüft nur, ob der Prozess antwortet und ob die PostgreSQL-Verbindung funktioniert. Externe Dienste wie Spotify oder YouTube Music werden dabei nie angefragt.

GET /api/v1/health ohne scope ergänzt lokale Diagnosen für yt-dlp, ffmpeg und ffprobe. Ein fehlendes Werkzeug ergibt den Status degraded, aber weiterhin HTTP 200. Nur eine nicht erreichbare Datenbank macht den Check mit HTTP 503 ungesund.

Frontend-Proxy und DNS ​

ytmdl-frontend liefert / statisch aus und reicht /api/* an backend:8080 weiter. Der Upstream steht dabei bewusst in einer nginx-Variablen:

nginx
set $ytmdl_backend http://backend:8080;
proxy_pass $ytmdl_backend;

Mit einem literalen Host löst nginx den Namen einmalig beim Start auf und behält die Adresse für die gesamte Laufzeit. Nach podman compose up -d --force-recreate backend hat der Backend-Container eine andere IP, und der Proxy antwortet dann dauerhaft mit 502. Über eine Variable findet die Auflösung pro Anfrage statt.

Dafür braucht nginx einen expliziten resolver. Dessen Adresse hängt vom Subnetz von ytmdl-net ab, weshalb sie nicht fest in der Konfiguration steht: docker-entrypoint.d/15-resolver.envsh liest beim Start den ersten nameserver aus /etc/resolv.conf des Containers und setzt ihn in die Vorlage ein. Ein geändertes Subnetz erfordert deshalb keine Anpassung am Frontend.

index.html wird mit Cache-Control: no-cache, must-revalidate ausgeliefert, die Dateien unter /assets/ mit immutable. Nur die Assets tragen einen Inhalts-Hash im Namen; eine gecachte index.html würde nach einem Update weiterhin auf die Bundles der vorherigen Version zeigen.

Der SSE-Strom /api/v1/events läuft durch denselben location-Block mit proxy_buffering off, damit Ereignisse den Browser sofort erreichen.

CI und Release über GitHub Actions ​

Die Entwicklung findet ausschließlich in Der-Felix/ytmdl auf GitHub statt. Pull Requests integrieren Änderungen nach dev; main bleibt der geprüfte stabile Stand. Promotion nach main, Release und Deployment sind separate Schritte.

Workflows unter .github/workflows/:

WorkflowAuslöserAufgabe
ci.ymlPR gegen dev/main, Push auf devTests und Builds; veröffentlicht nichts
release.ymlTag v*, manueller QualifikationslaufRelease-Qualifikation; Veröffentlichung nur bei Release-Tag
pages.ymlPush auf main, manueller LaufDokumentations-Deployment

CI und Release-Qualifikation starten PostgreSQL 18 als isolierten Test-Service und setzen MUSICDL_TEST_DATABASE_URL. Die Test-Zugangsdaten gelten ausschließlich für den kurzlebigen Dienst. Sie werden nicht für Deployments verwendet.

Versionierung und Registry ​

Der Release-Workflow prüft den Versions-Tag gegen .release-version, qualifiziert die Artefakte und veröffentlicht freigegebene Images unter ghcr.io/der-felix/ytmdl-backend:<version> und ghcr.io/der-felix/ytmdl-frontend:<version>. Erst nach erfolgreicher Qualifikation wird latest auf die geprüften Digests gesetzt. Die Registry-Anmeldung im GitHub-Workflow verwendet den kurzlebigen GITHUB_TOKEN.

Entwicklungs-PRs ändern weder Release-Tags noch Production. compose.yaml baut lokal; compose.ghcr.yaml beschreibt den offiziellen veröffentlichten Stack. Für einen tatsächlichen Release oder Rollout gilt der separat freigegebene Ablauf.

Lokale Anpassungen mit compose.ghcr.override.yaml ​

Für host-spezifische Ergänzungen zum offiziellen GHCR-Stack gibt es eine optionale Override-Datei compose.ghcr.override.yaml im Projektverzeichnis (neben compose.ghcr.yaml). Sie ist in .gitignore eingetragen und bleibt damit lokal — Updates überschreiben sie nie.

ytmdlctl bindet diese Datei automatisch ein. Bei Podman folgt sie nach compose.ghcr.podman.yaml, damit die lokalen Einstellungen zuletzt gelten.

Typischer Einsatz: einen zusätzlichen Bind-Mount oder eine Umgebungsvariable ergänzen, ohne die versionierte compose.ghcr.yaml zu verändern. Beispiel (mappt eine Host-Cookie-Datei in den Backend-Container; Pfad kommt aus .env):

yaml
services:
  backend:
    volumes:
      - ${YTMDL_YOUTUBE_COOKIE_PATH:?YTMDL_YOUTUBE_COOKIE_PATH must be set in .env}:/run/secrets/ytmdl-youtube.cookies.txt:rw,Z

Compose führt die beiden Dateien nach den üblichen Override-Regeln zusammen (zuletzt genannte Datei gewinnt bei gleichem Schlüssel; Listen wie volumes werden ergänzt).

Automatische Einbindung durch ytmdlctl ​

ytmdlctl (in der Version mit dieser Funktion) hängt -f compose.ghcr.override.yaml automatisch an jeden Compose-Aufruf an, sobald

  • die aufgelöste Compose-Datei compose.ghcr.yaml heißt und
  • compose.ghcr.override.yaml im selben Verzeichnis existiert.

Das gilt für alle intern ausgeführten Compose-Operationen (ps, port, pull, up, stop, exec, config …), also auch für ytmdlctl update, ytmdlctl backup und ytmdlctl rollback. Es ist keine zusätzliche Option nötig; fehlt die Datei, verhält sich ytmdlctl unverändert.

Manueller Aufruf mit beiden Dateien ​

Ohne ytmdlctl beide -f-Dateien in fester Reihenfolge angeben:

sh
podman compose -f compose.ghcr.yaml -f compose.ghcr.podman.yaml -f compose.ghcr.override.yaml up -d
# oder: docker compose -f compose.ghcr.yaml -f compose.ghcr.override.yaml up -d

Ältere ytmdlctl-Versionen ​

ytmdlctl-Versionen ohne diese Funktion binden die Override-Datei nicht automatisch ein und akzeptieren pro Aufruf nur ein einziges -f/--file. In dem Fall:

  • ytmdlctl auf eine Version mit Override-Unterstützung aktualisieren, oder
  • die Lifecycle-Schritte übergangsweise direkt über podman compose / docker compose mit beiden -f-Dateien ausführen. Dabei entfallen die transaktionalen Schutzmechanismen von ytmdlctl (verifizierter Pre-Update-Backup, Digest-Prüfung, Rollback) — nur als kurzfristiger Behelf verwenden.

Stop, Restart und Recovery ​

sh
podman compose -f compose.ghcr.yaml -f compose.ghcr.podman.yaml stop
podman compose -f compose.ghcr.yaml -f compose.ghcr.podman.yaml start

Podman sendet SIGTERM direkt an /app/musicdl. Das Backend sperrt daraufhin neue Jobs, trennt Event-Streams, fährt HTTP herunter, beendet Worker und die gesamte yt-dlp/ffmpeg-Prozessgruppe, setzt unterbrochene Arbeit zurück, schließt den Datenbankpool und beendet sich mit Exit-Code 0. Die stop_grace_period von 40s ist dafür großzügig bemessen; im Test dauert der Shutdown ein bis zwei Sekunden.

Das Recovery-Verhalten ist deterministisch und gilt gleichermaßen für einen sauberen SIGTERM, einen Absturz und einen Host-Neustart. Beim Herunterfahren und noch einmal beim Start gilt:

text
Job nicht terminal        → queued
JobItem in matching /
downloading / tagging     → pending (startet erneut bei matching)
Bereits fertige JobItems  → bleiben completed / failed / skipped

Damit bleibt kein Job dauerhaft in downloading stehen, kein Track wird doppelt heruntergeladen und keine Datei doppelt zugeordnet.

Backup und Restore ​

TIP

Für Installationen mit den offiziellen GHCR-Images ist ytmdlctl backup (verifizierter pg_dump -Fc inkl. pg_restore --list-Prüfung) der empfohlene Weg. Details, Umfang und Grenzen: Updates & Wartung → Datenbank-Backups. Die folgenden Compose-Befehle sind der manuelle Unterbau und funktionieren mit jeder Variante.

Sichern lassen sich Katalog und Bibliothek getrennt. Der Datenbank-Dump enthält nur den Katalog (Nutzer, Künstler, Alben, Tracks, Jobs, Playlists, Audits) — die Audiodateien unter ./music und optionale Dateien unter ./data (z. B. cookies.txt, hochgeladene Session-Cookies) müssen separat gesichert werden.

sh
# Datenbank sichern
podman compose exec -T db \
  pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc --no-owner > ytmdl.dump

# Bibliothek sichern
tar -czf music.tar.gz music

Zurückspielen:

sh
podman compose up -d db
podman compose exec -T db \
  pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" --clean --if-exists --no-owner < ytmdl.dump
podman compose up -d

Ein Klartext-Dump funktioniert genauso:

sh
podman compose exec -T db pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" > ytmdl.sql
podman compose exec -T db psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" < ytmdl.sql

Ein normales podman compose down entfernt Container und Netz, aber keine Daten: das Volume ytmdl-postgres-data und ./music bleiben erhalten, und ytmdl-net wird beim nächsten up mit demselben Subnetz neu angelegt. Nur podman compose down -v löscht das Volume und damit den Katalog.

Update ​

Offizielle Images (compose.ghcr.yaml): YTMDL_VERSION in .env anheben und ytmdlctl update ausführen — transaktional, mit verifiziertem Pre-Update-Backup, Digest-Prüfung und Rollback. Siehe Updates & Wartung mit ytmdlctl.

Lokaler Build (compose.yaml):

sh
git pull
podman compose down
podman compose build --no-cache
podman compose up -d

Migrationen laufen in beiden Fällen automatisch beim Start und sind gegen parallele Starts durch einen Advisory Lock abgesichert. Updates von Alpine, yt-dlp, ffmpeg oder PostgreSQL erfolgen reproduzierbar über ein neues Image bzw. einen neuen Build, nicht durch Änderungen im laufenden Container.

Logs ​

sh
podman compose logs -f backend
podman compose logs -f db

Das Backend schreibt strukturiertes JSON auf stdout (YTDM_LOG_FORMAT=text für lesbare Zeilen). Query-Strings, Credentials und Datenbankpasswörter erscheinen nicht im Log.

Direkter Podman-Betrieb ohne Compose ​

sh
podman network create --subnet 172.31.250.0/28 ytmdl-net
podman volume create ytmdl-postgres-data

podman run -d --name ytmdl-db \
  --network ytmdl-net --network-alias db \
  -e POSTGRES_DB=ytmdl -e POSTGRES_USER=ytmdl -e POSTGRES_PASSWORD=... \
  -v ytmdl-postgres-data:/var/lib/postgresql \
  docker.io/library/postgres:18-alpine

podman build -t ytmdl-backend -f Containerfile .
mkdir -p data music
podman run -d --name ytmdl-backend \
  --network ytmdl-net --network-alias backend \
  --userns=keep-id:uid=10001,gid=10001 \
  --env-file .env \
  -p 8080:8080 \
  -v "$(pwd)/data:/data:Z" \
  -v "$(pwd)/music:/music:Z" \
  ytmdl-backend

Die in .release-version abgelegte Version wird beim Build eingebettet. Ein expliziter Buildwert ist ebenfalls möglich:

sh
podman build --build-arg VERSION=0.4.0 -t ytmdl-backend:0.4.0 .

Podmans standardmäßiges OCI-Imageformat ignoriert Healthcheck-Metadaten aus einem Containerfile. compose.yaml setzt den identischen Check deshalb zusätzlich beim Erzeugen des Containers. Wer das Image direkt mit eingebettetem Healthcheck verwenden möchte, baut es im Docker-v2-Imageformat:

sh
podman build --format=docker -t ytmdl-backend .

Frontend-Container: ytmdl-frontend ​

Der Frontend-Container wird als Multi-Stage-Build gebaut:

text
Bun (Stage 1)  →  Frontend-Build  →  dist/  →  nginx:alpine (Stage 2)

Bun bleibt dabei reines Build-Werkzeug und läuft nicht als Produktions-Webserver. Nginx liefert die kompilierten statischen Assets aus, fängt SPA-Routen ab und leitet /api/* unbuffered (SSE-fähig) an das Backend weiter:

yaml
  frontend:
    build:
      context: ./frontend
      dockerfile: Containerfile
    image: ytmdl-frontend:${YTMDL_VERSION:-local}
    container_name: ytmdl-frontend
    depends_on:
      backend:
        condition: service_healthy
    ports:
      - "${YTMDL_HOST_PORT:-8080}:8080"
    networks:
      - ytmdl-net
    healthcheck:
      test:
        - CMD
        - wget
        - -q
        - -O
        - /dev/null
        - http://127.0.0.1:8080/
      interval: 15s
      timeout: 5s
      start_period: 5s
      retries: 3
    restart: unless-stopped

Released under the Apache 2.0 License.