Installation mit Docker

Tunetorch wird als Docker-Image ausgeliefert. Datenbank, Cache und FFmpeg stecken bereits darin — du brauchst nur Docker, idealerweise mit Docker Compose.

Schnellstart

Lege eine Datei docker-compose.yml an:

services:
  tunetorch:
    image: tunetorch/tunetorch:latest
    container_name: tunetorch
    restart: unless-stopped
    ports:
      - "5000:5000"
    volumes:
      # Datenverzeichnis — bitte regelmäßig sichern.
      - ./tunetorch-daten:/app/data

      # Optional: vorhandener Musikordner zum Scannen (immer read-only).
      # - /pfad/zu/deiner/musik:/app/musik:ro

      # Optional: Sammlung für den einmaligen Start-Import.
      # - /pfad/zu/deiner/sammlung:/app/import:ro

    # Eingestellt auf den Direktzugriff per HTTP — den Weg, den dieser
    # Schnellstart beschreibt. Hinter einem TLS-Reverse-Proxy beide Zeilen
    # wieder entfernen (siehe unten).
    environment:
      TT_HTTPS: "False"         # kein TLS: Cookies ohne Secure-Flag
      TT_TRUSTED_PROXIES: "0"   # kein Proxy davor
      # TT_PUID: "1000"         # UID des Volume-Eigentümers
      # TT_PGID: "1000"         # GID des Volume-Eigentümers

Starten:

docker compose up -d

Die Weboberfläche ist danach unter http://<server-adresse>:5000 erreichbar. Der erste Login läuft mit admin / BITTE_ÄNDERE_MICH; den Passwortwechsel erzwingt Tunetorch sofort (siehe Erste Schritte).

Die Volumes im Detail

Pfad im Container	Pflicht	Zweck
`/app/data`	ja	Datenbank, hochgeladene Audiodateien, Cover, Bilder, Logs, JWT-Schlüssel, Cache. Das ist das Verzeichnis, das du sichern musst.
`/app/musik`	nein	Ein bestehender Musikordner, den der Bibliothek-Scan einliest. Immer `:ro` einhängen — Tunetorch schreibt nie in deine Musikbibliothek.
`/app/import`	nein	Eine bestehende Sammlung für den einmaligen Start-Import. Ebenfalls `:ro`; nach dem Import kann der Mount wieder weg.

/app/data kannst du wahlweise als Bind-Mount (./tunetorch-daten:/app/data) oder als benanntes Volume (tunetorch_daten:/app/data) einhängen. Beim Bind-Mount solltest du TT_PUID/TT_PGID auf deinen Host-Benutzer setzen (id -u / id -g), damit du auch vom Host aus hineinschreiben kannst.

Der Container übereignet /app/data beim Start automatisch der eingestellten UID:GID — ein frisch als root angelegter Bind-Mount wird also von selbst beschreibbar. Nur wenn das scheitert (etwa wegen ACLs auf einer Synology), bricht der Start mit einer [entrypoint] FEHLER:-Meldung ab.

Nur Docker, ohne Compose

docker run -d \
  --name tunetorch \
  --restart unless-stopped \
  -p 5000:5000 \
  -v $(pwd)/tunetorch-daten:/app/data \
  tunetorch/tunetorch:latest

Ein bereitgestelltes Image laden

Wird dir das Image als Archiv geliefert:

docker load -i tunetorch-<VERSION>.tar.gz

Im Archiv trägt das Image seinen Bau-Namen (tunetorch:<VERSION>-<arch>), die Compose oben erwartet dagegen tunetorch/tunetorch:latest. Dazwischen gehört ein docker tag — ohne ihn scheitert der Start an einem „image not found", dessen Ursache nicht sichtbar ist:

docker tag tunetorch:<VERSION>-amd64 tunetorch/tunetorch:latest

Aktualisieren

docker compose pull
docker compose up -d

Deine Daten bleiben in /app/data erhalten. Schema-Änderungen zieht Tunetorch beim Start selbstständig nach — ein Update braucht keine Handarbeit.

Vor größeren Updates lohnt sich ein Backup des Datenverzeichnisses. Siehe Sicherheit & Datensicherung.

Betrieb hinter einem TLS-Reverse-Proxy

Der Schnellstart oben ist auf den Direktzugriff per HTTP eingestellt — daher die beiden Zeilen TT_HTTPS: "False" und TT_TRUSTED_PROXIES: "0". Läuft Tunetorch hinter einem Reverse-Proxy mit TLS (Caddy, Traefik, Nginx Proxy Manager), entferne beide wieder: Die Vorgaben True und 1 sind genau für diesen Fall gedacht. Der Proxy muss dabei X-Forwarded-Proto: https weiterreichen — daran erkennt Tunetorch die gesicherte Verbindung.

Dahinter steckt das Cookie-Verhalten der Browser: Mit TT_HTTPS: "True" setzt Tunetorch seine Anmelde-Cookies mit dem Secure-Flag. Kommt der Aufruf dann über http://, verwirft der Browser sie stillschweigend — die Anmeldung scheint fehlzuschlagen, obwohl der Server sie angenommen hat. Im Server-Log steht in diesem Fall eine Warnung, die genau das benennt.

Die Falle bei der Ersteinrichtung: Über http://localhost:5000 akzeptieren Chrome, Edge und Firefox Secure-Cookies trotzdem — localhost gilt ihnen als sicherer Kontext. Wer Tunetorch direkt auf dem Server einrichtet, merkt eine falsche Einstellung deshalb nicht; erst der Zugriff vom zweiten Gerät über die LAN-Adresse scheitert dann.

Wer die Wahl hat, sollte TLS vorziehen: TT_HTTPS: "False" ist die Lösung fürs Heimnetz ohne Zertifikat, nicht die bessere Betriebsart.

Mehr dazu unter Konfiguration.

Synology DSM

Auf Synology-Systemen gehört ein freigegebener Ordner oft nicht 1000:1000, sondern etwa 1026:100. Prüfe die Werte auf dem Host mit ls -ln auf das Volume-Verzeichnis und setze sie entsprechend:

    environment:
      TT_PUID: "1026"
      TT_PGID: "100"

Überstimmt eine ACL den automatischen Eigentümerwechsel, gib dem Benutzer mit dieser UID in der File Station zusätzlich explizit Schreibrecht.

Zwei weitere DSM-Eigenheiten kosten beim ersten Start regelmäßig Zeit: Port 5000 gehört der DSM-Oberfläche (wähle einen anderen Host-Port), und ein als /app/import oder /app/musik eingehängter freigegebener Ordner ist für den Container nicht automatisch lesbar — dass du ihn selbst in der File Station öffnen kannst, sagt darüber nichts aus. Beides samt Prüfbefehl steht auf der eigenen Seite Synology NAS (DSM).

Speicher für DLNA-Casting (optional)

Nutzt du DLNA-Casting mit Lautheits-Angleichung oder einem Ziel-Format, legt der Server kurzlebige Kopien des laufenden Titels an. Wo, entscheidet er selbst: bevorzugt im Arbeitsspeicher, sonst auf dem Datenträger. Damit läuft es ohne jede Anpassung.

Auf einem Server mit reichlich RAM kannst du die Kopien bewusst in den Arbeitsspeicher verlagern und der SD-Karte bzw. SSD Schreibzyklen sparen:

    shm_size: "1g"

Das ist eine Obergrenze, keine Reservierung — ungenutzt kostet sie nichts. Auf einem Raspberry Pi ist RAM allerdings knapper als Schreibzyklen; dort ist die Voreinstellung meist die bessere Wahl.

Gesundheitsprüfung

Das Image bringt einen HEALTHCHECK mit, der alle 30 Sekunden einen eigenen Endpunkt abfragt. docker ps zeigt den Container dadurch als healthy bzw. unhealthy — praktisch, um einen hängenden Server zu erkennen, den ein reines restart: unless-stopped nicht bemerken würde.

Der Start dauert je nach Hardware bis zu einer Minute (auf einer NAS gemessen: 44 Sekunden) — Redis, Schema-Prüfung und Server kommen nacheinander hoch. Der Container gilt in dieser Zeit noch nicht als healthy, und ein „Bad Gateway“ vom Reverse-Proxy ist normal und verschwindet von selbst. Bleibt er dauerhaft, liegt die Ursache woanders — siehe Fehlerbehebung.

docker ps
docker compose logs -f tunetorch

Nächster Schritt

Konfiguration — Umgebungsvariablen und Server-Einstellungen
Bibliothek befüllen — Musik hineinbringen