1. Introduction
Changing the timezone in a Docker container can be done in many different ways. It may depend on whether we want to set it before creating the container or at runtime.
In this tutorial, we’ll examine the four most common methods for changing the timezone in a Docker container.
First, we’ll briefly cover the concept of a timezone and the basics of its configuration. Next, let’s learn how to set the timezone by changing Dockerfile. Afterward, we’ll see a method based on using Docker Compose. Then, we’ll look at a method for setting the timezone when creating the container using the docker run command. Finally, we’ll learn how to set the timezone by accessing the shell of a running Docker container.
2. How is the Timezone Set Up?
We can define a timezone as an area that observes a uniform standard time for legal, commercial, and social purposes.
The tzdata package contains data files describing current and historic transitions in various timezones worldwide. Thus, to change the timezone of a Docker container, we need to configure the container using the resources provided by tzdata.
Basically, we need to install the tzdata package in the container (if it hasn’t already been installed) and specify the timezone in an environment variable. Next, we’ll examine different ways of accomplishing this task.
3. Setting the Timezone Before Creating the Container
An effective way to set the timezone of a Docker container is to do so before creating it. Below, we’ll look at three different ways of doing this.
3.1. Setting the Timezone via Dockerfile
A Dockerfile is a plain text file that contains all the instructions required for building a given Docker image. Using a Dockerfile, we can, for example, define a base image, set environment variables, and specify commands that the Docker daemon will automatically execute when building the image.
Therefore, via Dockerfile, we can configure the timezone of a Docker container during the image build process. This method is ideal if we want the timezone change to be part of the image and affect all containers built from it.
Basically, we can set the timezone using a Dockerfile, adding an instruction to set the desired timezone to an environment variable called TZ:
ENV TZ=<timezone>
However, if the image we’re using doesn’t already have the tzdata package installed, we must first install and configure it. The following example demonstrates a simple Dockerfile to build an Nginx image with the timezone set to America/New_York.
# Use the official Nginx base image
FROM nginx:latest
# Set the environment variable for the timezone
ENV TZ=America/New_York
# Install the tzdata package to configure the timezone
RUN apt-get update && \
apt-get install -y tzdata && \
ln -sf /usr/share/zoneinfo/$TZ /etc/localtime && \
echo $TZ > /etc/timezone && \
apt-get clean && \
rm -rf /var/lib/apt/lists/*
Next, we can build the image by running the command below. The -t flag specifies a tag for the image, allowing us to assign a name and version to it using the
$ docker build -t nginx-america-ny-timezone:latest .
Then, we can create a container using the generated image as follows:
$ docker run --name my-nginx-container nginx-america-ny-timezone:latest
Finally, we can check the timezone:
$ docker exec my-nginx-container date
Wed Jun 26 08:24:07 EDT 2024
The acronym EDT stands for Eastern Daylight Time, which is one of the well-known names of the UTC-4 timezone. The EDT is currently observed by many regions, including America/New_York. Therefore, the configuration had the expected effect.
3.2. Setting the Timezone Using Docker Compose
Docker Compose is a tool that allows us to easily run single or multi-container applications. Using Docker Compose, we can specify an entire application stack by adding rules to a single, comprehensible YAML configuration file, called docker-compose.yml.
Therefore, when we’re using Docker Compose to manage containers, we can declare the timezone directly as an environment variable in the docker-compose.yml file:
environment:
- TZ=<timezone>
Below is an example of a Docker Compose file that builds and runs an Nginx service with the timezone set to America/New_York.
version: '3.8'
name: my-nginx-container
services:
my-service:
image: nginx:latest
build:
context: .
dockerfile: Dockerfile
environment:
- TZ=America/New_York
ports:
- "8080:80"
We can test these settings by creating a container based on the docker-compose.yml file above, as follows:
$ docker compose up --build
This command will build the Nginx image with the specified timezone and start the container. So, now we can check the result:
$ docker exec my-nginx-container-my-service-1 date
Wed Jun 26 08:28:51 EDT 2024
3.3. Setting the Timezone Using the docker run Command
The docker run command allows us to create and run a new container from a Docker image. In addition, using this command, we can define the container’s attributes when creating it. This allows us, for example, to set environment variables using the -e flag, following the syntax -e VAR1=value1.
As we mentioned previously, we can choose the timezone for a container during the creation process by setting the desired timezone to an environment variable called TZ. Therefore, we can, for example, create an Nginx container with the timezone set to America/New_York using the docker run command as follows.
$ docker run -e TZ=America/New_York nginx:latest
This command will only affect the container instance that will be created (not the image). However, they’ll only work successfully if the tzdata package is already installed in the container. In case the tzdata package isn’t installed, we recommend using the previous methods.
4. Setting the Timezone in Runtime
The most effective way to set the timezone in a running Docker container is to access the container shell in an interactive mode. We can do this using the docker exec command as follows:
$ docker exec -it my-nginx-container /bin/bash
As a result, we’ll have access to the container’s shell. Next, if the Docker image of the container doesn’t have the tzdata package installed, we can install it by running:
apt-get update
apt-get install -y tzdata
Then, we can configure the timezone in this container instance.
ln -sf /usr/share/zoneinfo/America/New_York /etc/localtime
echo America/New_York > /etc/timezone
Finally, we can check the timezone:
date
Wed Jun 26 08:35:22 EDT 2024
5. Conclusion
In this tutorial, we explored different methods for changing the timezone in a Docker container.
By using Dockerfile or Docker Compose, we can define a specific timezone even before creating the container. Alternatively, we can use the docker run command to set the timezone of a Docker container during the creation process. Finally, we can interactively change the timezone in a running container by using the shell.