Verwendung der TZ-Zeitzonenangabe in Docker: Anleitung und verfügbare Zeitzonen

Die TZ-Zeitzonenangabe in Docker sorgt dafür, dass deine Container mit der richtigen lokalen Uhrzeit arbeiten – unabhängig davon, in welcher Zeitzone der Host oder der Cloud-Server läuft. Gerade bei Logs, Cron-Jobs und zeitgesteuerten Abläufen ist das entscheidend, denn eine falsch gesetzte Zeitzone führt schnell zu verwirrenden Zeitstempeln oder Aufgaben, die zur falschen Uhrzeit starten. In dieser Anleitung erfährst du, wie du die TZ-Umgebungsvariable setzt, wie sie sich auswirkt und welche Zeitzonen dir zur Verfügung stehen.

Was ist die TZ-Umgebungsvariable?

Die TZ-Umgebungsvariable ist ein Standardmechanismus unter Linux, mit dem du die Zeitzone eines Prozesses festlegst. Programme lesen diese Variable aus und richten ihre Zeitberechnung danach aus. In einem Docker-Container funktioniert das genauso: Setzt du TZ beim Start, verwendet der Container die angegebene Zeitzone statt der Standardvorgabe.

Standardmäßig starten die meisten offiziellen Images in der Zeitzone UTC. Das ist bewusst so gewählt, weil UTC keine Sommer-/Winterzeit kennt und weltweit eindeutig ist. Für viele Anwendungen – etwa Datenbanken – ist UTC sogar die empfohlene Einstellung. Sobald du aber lokale Zeitstempel oder lokal getaktete Aufgaben brauchst, willst du die Zeitzone gezielt überschreiben.

Warum ist die Zeitzonenkonfiguration wichtig?

Eine korrekt gesetzte Zeitzone ist in mehreren Situationen entscheidend:

• Zeitstempel: Anwendungen, die Zeitstempel erzeugen (etwa in Logs oder Datenbankeinträgen), schreiben diese in der eingestellten Zeitzone. Das erleichtert die spätere Auswertung erheblich.
• Geplante Aufgaben: Cron-Jobs und andere zeitbasierte Prozesse laufen nur dann zur erwarteten lokalen Uhrzeit, wenn die Zeitzone stimmt.
• Globale Anwendungen: Wird deine Anwendung von Nutzern in verschiedenen Regionen genutzt, sorgt die richtige Zeitzone für nachvollziehbare, korrekt lokalisierte Zeitangaben.

So verwendest du die TZ-Zeitzonenangabe in Docker

Um die Zeitzone eines Containers festzulegen, übergibst du die TZ-Umgebungsvariable beim Start. Das geht über den Schalter -e (bzw. --env) im docker run-Befehl, über eine docker-compose.yml oder direkt im Image über das ENV-Statement im Dockerfile. Am flexibelsten ist die Variante über eine Umgebungsvariable, weil du dieselbe Image-Basis in unterschiedlichen Zeitzonen betreiben kannst.

Beispiel 1: Container mit fester Zeitzone starten

Angenommen, du möchtest einen Container in der Zeitzone „Europe/Berlin“ starten. Dann verwendest du folgenden Befehl:

docker run -e TZ=Europe/Berlin dein-image

Der Container läuft nun in Berliner Zeit, egal welche Zeitzone das Host-System nutzt. Prüfen kannst du das direkt im laufenden Container mit dem date-Befehl:

docker exec mein-container date

Beispiel 2: Zeitzone in Docker Compose setzen

Wenn du deine Container mit Docker Compose verwaltest, hinterlegst du die Zeitzone im environment-Abschnitt des jeweiligen Dienstes. Das ist übersichtlich und lässt sich versionieren:

services:
  app:
    image: dein-image:latest
    environment:
      - TZ=Europe/Berlin
    restart: unless-stopped

Mehr zum Umgang mit Umgebungsvariablen in Compose – etwa über eine zentrale .env-Datei – findest du in unserem Beitrag zu Umgebungsvariablen in Docker Compose. Wie du mit der restart-Direktive dafür sorgst, dass Container automatisch wieder anlaufen, zeigt unsere Anleitung zur Docker Restart Policy.

Beispiel 3: Zeitzone fest im Dockerfile hinterlegen

Soll ein Image von vornherein eine bestimmte Zeitzone mitbringen, setzt du TZ direkt im Dockerfile. Bei manchen schlanken Images musst du zusätzlich die passenden Zeitzonendaten installieren und den Symlink setzen:

FROM ubuntu:22.04
ENV TZ=Europe/Berlin
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone

Der ln-Befehl verknüpft die Systemzeit fest mit der gewünschten Zeitzone. In vielen offiziellen Images reicht allerdings schon das reine Setzen von ENV TZ, weil die Zeitzonendaten bereits enthalten sind.

Auswirkungen der TZ-Zeitzonenangabe

Setzt du die TZ-Variable, wirkt sich das an mehreren Stellen aus:

• Systemzeit im Container: Alle zeitabhängigen Operationen im Container basieren auf der festgelegten Zeitzone.
• Logs und Zeitstempel: Jede erzeugte Zeitangabe – etwa in Logdateien – wird in der eingestellten Zeitzone ausgegeben.
• Geplante Aufgaben: Cron-Jobs und andere zeitbasierte Aufgaben laufen zur korrekten lokalen Zeit der angegebenen Zeitzone.

Wichtig: Die TZ-Variable ändert nur die Darstellung und Berechnung der lokalen Zeit. Der zugrunde liegende UTC-Zeitpunkt bleibt derselbe. Wenn Anwendungen intern konsequent mit UTC arbeiten, ist das ein Vorteil – die lokale Zeitzone dient dann vor allem der lesbaren Ausgabe.

Liste der verfügbaren Zeitzonen

Docker unterstützt alle Zeitzonen der IANA-Zeitzonendatenbank (auch tz database genannt). Die Angaben folgen dem Format „Region/Stadt“. Hier eine Auswahl häufig genutzter Zeitzonen:

• UTC – Koordinierte Weltzeit, weltweiter Standard
• Europe/Berlin – Mitteleuropäische Zeit
• Europe/London – Britische Zeit
• America/New_York – US-Ostküste
• America/Los_Angeles – US-Westküste
• Asia/Tokyo – Japanische Zeit
• Asia/Shanghai – Chinesische Zeit
• Australia/Sydney – Ostaustralische Zeit
• Africa/Johannesburg – Südafrikanische Zeit
• Pacific/Auckland – Neuseeländische Zeit

Eine vollständige Liste aller Zeitzonen zeigt dir dein Linux-System mit folgendem Befehl an:

timedatectl list-timezones

Alternativ findest du die komplette Übersicht auch online in der Liste der IANA-Zeitzonen. Achte darauf, den Bezeichner exakt zu übernehmen, denn Docker akzeptiert nur die offiziellen IANA-Namen.

Zeitzone im laufenden Container prüfen und Fehler vermeiden

Kommt es trotz gesetzter TZ-Variable zu falschen Zeiten, hilft eine kurze Kontrolle. Diese Punkte solltest du prüfen:

• Tippfehler im Bezeichner: Europe/Berlin ist korrekt, Europe/berlin hingegen nicht. Groß-/Kleinschreibung und Schreibweise müssen exakt stimmen.
• Fehlende Zeitzonendaten: Sehr schlanke Images (etwa auf Alpine-Basis) bringen mitunter das Paket tzdata nicht mit. Installiere es im Dockerfile nach, falls die Zeitzone ignoriert wird.
• Neustart nötig: Änderst du die Umgebungsvariable, musst du den Container neu erstellen – ein einfacher Neustart ohne neue Variable reicht nicht.

Fazit

Die TZ-Zeitzonenangabe in Docker ist der einfachste Weg, Container mit der richtigen lokalen Uhrzeit zu betreiben. Du setzt die TZ-Umgebungsvariable per docker run, in der docker-compose.yml oder direkt im Dockerfile und stellst so sicher, dass Logs, Zeitstempel und geplante Aufgaben zur erwarteten Zeit laufen. Achte auf die exakten IANA-Bezeichner und prüfe bei schlanken Images, ob die Zeitzonendaten vorhanden sind – dann arbeitet dein Container zuverlässig in jeder gewünschten Zeitzone.

Häufige Fragen (FAQ)

Welche Zeitzone nutzt ein Docker-Container standardmäßig?

Die meisten offiziellen Images starten in UTC. UTC ist eindeutig und kennt keine Sommer-/Winterzeit, weshalb es sich besonders für Server und Datenbanken eignet. Erst durch das Setzen der TZ-Variable wechselst du auf eine lokale Zeitzone.

Wie setze ich die Zeitzone in Docker Compose?

Trage im jeweiligen Dienst unter environment den Eintrag - TZ=Europe/Berlin ein. Nach einem docker compose up -d übernimmt der Container die neue Zeitzone. Bestehende Container musst du dafür neu erstellen.

Warum ändert sich die Zeit im Container trotz TZ-Variable nicht?

Meist fehlen bei sehr schlanken Images die Zeitzonendaten. Installiere in diesem Fall das Paket tzdata im Dockerfile nach. Prüfe außerdem, ob du den Bezeichner exakt geschrieben und den Container nach der Änderung neu erstellt hast.

Wo finde ich eine Liste aller gültigen Zeitzonen?

Auf einem Linux-System listet timedatectl list-timezones alle verfügbaren Zeitzonen auf. Online findest du dieselben Bezeichner in der IANA-Zeitzonendatenbank. Verwende immer das Format „Region/Stadt“.

Sollte ich Container besser in UTC oder in lokaler Zeit betreiben?

Für Datenbanken und interne Verarbeitung ist UTC meist die bessere Wahl, weil es global eindeutig ist. Für Anwendungen mit lokal getakteten Aufgaben oder gut lesbaren Logs bietet sich eine passende lokale Zeitzone über die TZ-Variable an.