Mein optimiertes docker-compose.yml für Paperless-NGX auf der UGREEN-NAS

Nach ein paar Iterationen hat sich bei mir diese docker-compose.yml als stabil und gut wartbar herausgestellt.
Wichtig dabei: Alle Images sind bewusst auf feste Versionen gepinnt, damit Updates nur dann passieren, wenn ich sie wirklich möchte – und nicht heimlich im Hintergrund.

# Docker Compose für Paperless-NGX auf meiner UGREEN-NAS

services:
  broker:
    image: docker.io/library/redis:7.4.3
    restart: unless-stopped
    volumes:
      - redisdata:/data

  db:
    image: docker.io/library/postgres:16
    restart: unless-stopped
    volumes:
      - /volume1/docker/paperless/database:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: EinSehrLangesUndSicheresPasswort

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:2.19.6
    restart: unless-stopped
    depends_on:
      - db
      - broker
      - gotenberg
      - tika
    ports:
      - "8010:8000"
    volumes:
      - /volume1/docker/paperless/data:/usr/src/paperless/data
      - /volume1/docker/paperless/media:/usr/src/paperless/media
      - /volume1/docker/paperless/export:/usr/src/paperless/export
      - /volume1/docker/paperless/consume:/usr/src/paperless/consume
    env_file: docker-compose.env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_CONSUMER_ENABLE_BARCODES: true
      PAPERLESS_TIKA_ENABLED: 1
      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
      PAPERLESS_TIKA_ENDPOINT: http://tika:9998
      PAPERLESS_EMAIL_TASK_CRON: "0 */8 * * *"  # alle acht Stunden

  gotenberg:
    image: docker.io/gotenberg/gotenberg:8.7
    restart: unless-stopped
    # Chromium wird nur für lokale Inhalte genutzt, kein externes Nachladen
    command:
      - "gotenberg"
      - "--chromium-disable-javascript=true"
      - "--chromium-allow-list=file:///tmp/.*"

  tika:
    # WICHTIG: Hier KEIN 'latest', sondern eine aktuell freigegebene 2.x-Version
    # Beispiel beim Schreiben dieses Artikels:
    # image: docker.io/apache/tika:2.9.1
    image: docker.io/apache/tika:2.9.1
    restart: unless-stopped

volumes:
  redisdata:

Hinweis für die Leser:
Die Versionsnummern (vor allem bei Paperless-NGX und Tika) sind Beispiele.
Im Zweifel immer in der Paperless-NGX-Dokumentation und auf Docker Hub nachsehen, welche aktuelle 2.x-Tika-Version empfohlen ist – und genau diese als Tag eintragen, nicht latest.

Warum wir Versionen festhalten und nicht „latest“ nutzen

Ich habe am Anfang auch „einfach immer die neueste Version gezogen“. Das hat so lange gut funktioniert, bis sich eine Abhängigkeit geändert hat und plötzlich Dinge anders liefen als erwartet. Spätestens dann lernt man:

Stabilität schlägt Bequemlichkeit.

1. Reproduzierbarkeit

Wenn ich in der Compose schreibe:

image: ghcr.io/paperless-ngx/paperless-ngx:2.19.6

dann weiß ich:

• Auf meiner UGREEN-NAS läuft genau diese Version.
• Wenn ich das System neu aufsetze, bekomme ich exakt denselben Stand.
• Wenn ich docker compose pull ausführe, ziehe ich nicht „irgendwas Neues“, sondern genau das, was ich vorher bewusst freigegeben habe.

Mit latest hast du diese Kontrolle nicht. Da entscheidet die Registry, was du beim nächsten Pull bekommst.

2. Sicherheit & Datenbank-Stabilität

Gerade bei PostgreSQL ist das wichtig:

image: docker.io/library/postgres:16

• Bleibt die Major-Version gleich (z. B. 16.x), ist das für Paperless unkritisch.
• Springt man unkontrolliert z. B. auf 17, braucht es oft Migrationsschritte.

Mit einem festen Tag kannst du das sauber planen:
Backup ? Tag ändern ? testen.
Ohne festen Tag merkst du das Problem oft erst, wenn Paperless nicht mehr startet.

3. Keine Überraschungen bei Gotenberg & Tika

Gotenberg und Tika sind die Spezialisten im Hintergrund:

• Gotenberg kümmert sich um Office-Dokumente / E-Mail-Konvertierung
• Tika extrahiert Inhalte, Texte, Metadaten

Beide Projekte entwickeln sich weiter – neue Major-Versionen ändern teilweise Verhalten und Schnittstellen. Wenn man hier stumpf latest nutzt, kann es passieren, dass:

• Logs plötzlich voll Fehler laufen
• Anhänge nicht mehr richtig verarbeitet werden
• OCR-Ergebnisse sich ändern
• Dokumente nicht wie erwartet erkannt werden

Deshalb:

• Gotenberg bewusst auf eine 8.x-Version pinnen, z. B. 8.7
• Tika bewusst auf eine 2.x-Version pinnen, z. B. 2.9.1 – oder eben die Version, die Paperless-NGX in der Dokumentation aktuell empfiehlt

4. Warum wir bei Tika „nur die aktuell freigegebenen“ nehmen

Viele stolpern bei Tika über das latest-Tag. Klingt bequem, ist aber tückisch.

Mein Ansatz (und den empfehle ich den Lesern):

1. In der Paperless-NGX-Dokumentation oder auf Docker Hub nachsehen, welche Tika 2.x-Version aktuell stabil ist.
2. Diese Version bewusst in der Compose eintragen, z. B.:

tika:
  image: docker.io/apache/tika:2.9.1

1. Erst wenn man später bewusst updaten will, den Tag anpassen – nicht automatisch über latest.

Damit erfüllen wir genau das, was wir wollen:

• Immer eine aktuelle, freigegebene Tika-Version nutzen
• Aber eben bewusst und kontrolliert – und nicht „Überraschung bei jedem Pull“.

Und was machen wir, wenn eine neue Paperless-Version kommt?

Genau deshalb pinnen wir die Versionen:

• Wenn eine neue Paperless-Version erscheint, schauen wir erst in die Release-Notes.
• Dann prüfen wir: braucht es eine Datenbank-Migration, neue Variablen, Änderungen bei Tika/Gotenberg?
• Erst danach passen wir die Tags in der Compose an und fahren ein geplantes Update.

So bleibt das System stabil – und wir entscheiden, wann sich etwas ändert, nicht der Zufall.