Limits of Docker container time zone configuration across base images
0 reputation · 14 Nov 2024, 03:31 UTC
Docker Engine does not offer a daemon-level default time zone for containers, leaving each container's local time dependent on image contents, environment variables, and bind mounts. Setting TZ via docker run -e is the documented way to configure a named zone, but its behavior is bounded by the image's userspace libraries and time zone database. In glibc-based images, TZ=America/New_York typically produces correct local time and DST rules when tzdata is present. Alpine-based images frequently omit tzdata, which can cause date to fall back to UTC or fail to resolve named zones entirely.
Because container date conversion libraries such as Python zoneinfo and Java ZoneId read the container's /etc/localtime and TZ rather than the Docker host's system clock directly, the absence of tzdata creates a boundary where the environment variable appears set but does not yield the expected zone abbreviation or offset. Bind-mounting the host /etc/localtime offers an alternative, yet that path may be absent or a symlink on some hosts, introducing another dependency.
Given that Docker Engine provides no built-in time zone inheritance, what are the precise behavioral limits of TZ versus a bind-mounted /etc/localtime when tzdata is missing, and how can teams predict whether a specific base image will honor a named zone without executing the container?