add tzdata package

[mmichalak-swe]

Changes

• Add tzdata package to Docker image

Reason

Installing tzdata provides the system timezone database and allows the container timezone to be configured via the TZ environment variable.

[m90]

I'm a bit torn on this one, mostly because of not wanting to change things that currently work as intended. I would definitely think this is something to include in a v3, yes.

One big question in here would be: considering this would be merged and users that currently mount their TZ data as it's done right now updated without changing their config, would their setups still continue to work?

[mmichalak-swe]

I just tested it by using my custom image (only adding tzdata to the existing v2.47.2 image), and commenting out the bind mounts:

environment:
  - TZ=${TZ}
image: offen/docker-volume-backup:v2.47.2-tzdata-test
volumes:
  # - /etc/timezone:/etc/timezone:ro
  # - /etc/localtime:/etc/localtime:ro
  # - /usr/share/zoneinfo:/usr/share/zoneinfo:ro

I also tried the custom image with tzdata added, against my old configuration (without a TZ variable, and with the bind mounts):

environment:
#   - TZ=${TZ}
image: offen/docker-volume-backup:v2.47.2-tzdata-test
volumes:
  - /etc/timezone:/etc/timezone:ro
  - /etc/localtime:/etc/localtime:ro
  - /usr/share/zoneinfo:/usr/share/zoneinfo:ro

I then tried using the custom tzdata image, with both configurations enabled together:

environment:
  - TZ=${TZ}
image: offen/docker-volume-backup:v2.47.2-tzdata-test
volumes:
  - /etc/timezone:/etc/timezone:ro
  - /etc/localtime:/etc/localtime:ro
  - /usr/share/zoneinfo:/usr/share/zoneinfo:ro

All cases are working as expected, producing the expected time with the date command, while also creating a local backup with the correct time. Additionally, this worked while stopping and starting a container to perform the backup. I understand your hesitation, but I think this is a low-risk change with a lot of upside. To set my timezone correctly, I had to read the documentation, and then follow the guidance given in #28. That is a lot of effort for what should be a simple setting, that some users might miss!

Perhaps it is better saved for v3, but I think this functionality could be enabled without issue immediately.

[m90]

To set my timezone correctly, I had to read the documentation, and then follow the guidance given in #28.

What info was missing from the docs that you could find in #28 only?

[mmichalak-swe]

From #28 (comment)

/usr/share/zoneinfo:/usr/share/zoneinfo:ro

Page it's missing from: set container timezone

services:
  backup:
    image: offen/docker-volume-backup:v2
    volumes:
      - data:/backup/my-app-backup:ro
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro

volumes:
  data:

I can edit and open a PR to fix

[m90]

I can edit and open a PR to fix

That'd be grand 🎩

[mmichalak-swe]

Continuing our conversation here...

Thanks! I guess I'll need a little more time to ponder #748, I hope that's ok.

No worries. I can do some more testing and report back. I was doing some research on ChatGPT and it agrees that it's a low-risk change. I think the testing I did above will cover users that upgrade to a new image that includes tzdata, while their configuration may still contain the bind mounts (the bind mounts would take precedence). Let me know if there's anything else I can help you with on this.

[le-lenn]

Id like to throw my hat in the ring for this addition to the codebase.

The current way of binding the OS host timezone did work for me as intended, but it feels a bit awkward as I am depending on an upstream config of my host system. Which could change. Being able to set the time zone explicitly (and also in only 1 line) would feel like a great ease of life feature.

one question that comes to mind:
What happens if both config options are set and are conflicting? Which is prioritized?

Also, if this is added, it would be great if the time zone would be logged on startup (“Timezone set to “Europe/Berlin via environment variable.”)

I also feel that the very slim increase in image size is worth it.

[mmichalak-swe]

What happens if both config options are set and are conflicting? Which is prioritized?

@le-lenn great question. In short, if both are set, the timezone set by the env variable TZ (used by the tzdata package) will take precedence:

Configuration	Settings	Image	Command	Result
1	No TZ variable, bind mounts	v2.47.2	$ docker exec -it volume-backup date	Sat Mar 21 12:19:41 EDT 2026
2	No TZ variable, bind mounts	v2.47.2-tzdata-test	$ docker exec -it volume-backup date	Sat Mar 21 12:20:30 EDT 2026
3	TZ variable set to something different (America/Los_Angeles) from my host's timezone (America/New_York), bind mounts	v2.47.2-tzdata-test	$ docker exec -it volume-backup date	Sat Mar 21 09:21:04 PDT 2026

For configurations 2 and 3, I am using an image created with the following Dockerfile:

FROM offen/docker-volume-backup:v2.47.2
RUN apk add tzdata curl jq --no-cache

Configuration 1:

    environment:
      # - TZ=America/Los_Angeles
    image: offen/docker-volume-backup:v2.47.2
    volumes:
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
      - /usr/share/zoneinfo:/usr/share/zoneinfo:ro

Configuration 2:

    environment:
      # - TZ=America/Los_Angeles
    image: offen/docker-volume-backup:v2.47.2-tzdata-test
    volumes:
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
      - /usr/share/zoneinfo:/usr/share/zoneinfo:ro

Configuration 3:

    environment:
      - TZ=America/Los_Angeles
    image: offen/docker-volume-backup:v2.47.2-tzdata-test
    volumes:
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
      - /usr/share/zoneinfo:/usr/share/zoneinfo:ro

Configuration 1 represents users today, and configuration 2 represents a new image with tzdata added. This is an important test, because it shows that the bind mounts take precedence over the addition of the tzdata package, without TZ set in the container. When users upgrade to a newer image, keep the bind mounts, but do not set TZ, their configuration will still work as it does today.

Configuration 3 shows that when TZ is set, it will override the settings from the host that are bind-mounted inside the container. I live in the America/New_York timezone, but when I set TZ to America/Los_Angeles, the timezone inside the container is superseded by what TZ is set to, even though the bind mounts from my host are still active.

I would argue that there is no need to print the current timezone upon container start, it is UTC by default. If a user modifies it from the default, they should know what they are updating it to. Worst case users can run the date command inside the container to confirm.

I like your point about the dependency created by the upstream host. The tzdata package allows for better isolation from the host, and better control over the time/timezone inside the container, regardless of the platform it is running on. It is a better design for containerization.

Let me know if there's anything I can clarify.

[m90]

I guess it makes sense to do this, yes.

A few more remarks from my end:

• should the image print a deprecation warning if the old mechanism is used? Is it even possible to know if the old mechanism is used (i.e. can we check if a file is a bind mount?)
• can you also update the documentation in this PR?
• I also wouldn't want to print any info on the configured timezone on startup, it's fine if users can run date

[le-lenn]

My line of thinking with printing the configured time zone on startup was to have a way to catch accidental misconfigurations and warn the user about it.
What happens when I misspell the time zone? (i.e “Europe/Berlinn”). Would the time zone silently be set to UTC without any warning?

[mmichalak-swe]

@le-lenn the time zone defaults (without warning) to UTC if you do not provide a valid tz database time zone

@m90 we should be able to add a script that does something similar to the following:

$ docker exec -it volume-backup cat /proc/self/mountinfo | grep -E '/etc/timezone|/etc/localtime|/usr/share/zoneinfo'
544 531 252:0 /etc/timezone /etc/timezone ro,relatime - ext4 /dev/mapper/ubuntu--vg-ubuntu--lv rw
545 531 252:0 /usr/share/zoneinfo/America/New_York /etc/localtime ro,relatime - ext4 /dev/mapper/ubuntu--vg-ubuntu--lv rw
549 531 252:0 /usr/share/zoneinfo /usr/share/zoneinfo ro,relatime - ext4 /dev/mapper/ubuntu--vg-ubuntu--lv rw

A possible script could look something like this:

#!/bin/sh

# List of deprecated bind-mount targets
DEPRECATED_MOUNTS="/etc/timezone /etc/localtime /usr/share/zoneinfo"
FOUND_DEPRECATED=false

for mnt in $DEPRECATED_MOUNTS; do
    # Check if the path is explicitly listed as a mount point
    if grep -q " $mnt " /proc/self/mountinfo; then
        echo "WARNING: Bind-mounting '$mnt' is DEPRECATED."
        FOUND_DEPRECATED=true
    fi
done

if [ "$FOUND_DEPRECATED" = true ]; then
    echo "-------------------------------------------------------------------"
    echo "Use the 'TZ' environment variable to set the time zone"
    echo "Please see the documentation for more details"
    echo "-------------------------------------------------------------------"
fi

# Continue to main application
exec /usr/bin/backup -foreground "$@"

This script would become the new entrypoint in the Dockerfile, and it could then call your current entrypoint. I will test this out.