Docker Compose Environment Variables: How to Set and Use Them Effectively

Docker environment variables play an essential role in configuring and managing applications that are containerized. This gives developers the perfect opportunity to define dynamic values that can be used within the Docker containers without actually modifying the application code. 

Docker environment variables help with: 

• Configuration Management: Switch between different configurations (e.g., development, staging, and production).
• Security: Avoid hardcoding sensitive information like API keys and passwords in Dockerfiles.
• Portability: Ensure consistent behavior across different environments and deployment setups.

Docker provides multiple ways to define and use environment variables, such as: 

1. Docker Compose Environment Variables (docker-compose.yml) – Define variables in an environment section or an external .env file.
2. Dockerfile (ENV instruction) – Set default environment variables at the image level.
3. docker run command – Pass environment variables dynamically when running a container.

In this guide, we will walk through all these methods and learn the best ways to manage variables effectively in a Docker file. 

Types of Docker Environment Variables

Docker provides two primary types of environment variables:

1. ENV (Environment Variables in Running Containers)

A Dockerfile uses ENV command to define Docker environment variables that persist in a running container. These can be accessed within the container by applications. 

Example:

FROM ubuntu:latest  

ENV APP_ENV=production  

CMD echo “Running in $APP_ENV mode”

• These variables are set at build time but can be overridden at runtime using the -e flag with docker run.
• They are useful for defining configurations like database URLs and API keys. 

2. ARG (Build-Time Variables)

The ARG command in Dockerfile defines variables that are only accessible during the image build process. These variables cannot be accessed after the container starts. 

Example:

FROM ubuntu:latest  

ARG VERSION=1.0  

RUN echo “Building version $VERSION”

• ARG variables are useful for passing build-specific values such as software versions or package names.
• They can be set using the –build-arg flag with docker build.

Key Differences Between ENV and ARG:

Feature	ENV	ARG
Available at Build Time	✅	✅
Available at Runtime	✅	❌
Can Be Overridden at Runtime	✅	❌
Persist in the Container	✅	❌

Why Use Docker Compose Environment Variables?

Docker compose environment variables provide an easy way to configure applications without modifying source code. Here’s why they are useful: 

1. Easier Configuration Management

In place of hardcoding values in the docker-compose.yml file, you can use variables to make deployments more dynamic. 

2. Improved Security

Sensitive & secret information like database passwords and API keys can be stored in an .env file instead of being exposed in the configuration file. 

3. Portability Across Environments

Docker-compose environment variables help adapt the same Docker setup for different environments (e.g. development, staging, and production) without modifying the docker-compose.yml file. 

4. Simplifies Updates and Maintenance

Updating configurations is easy since changes can be made in the .env file without modifying the application file. 

Example: Using Environment Variables in Docker Compose

version: ‘3’

services:

  app:

    image: my-app

    environment:

      – DATABASE_URL=${DATABASE_URL}

By using an .env file:

DATABASE_URL=mysql://user:password@db:3306/mydatabase

This setup ensures that the database URL is not exposed in the docker-compose.yml file, making deployments more secure and manageable.

Setting Up Environment Variables in Docker Compose

Docker compose provides multiple ways to set up variables, making it super simple to manage dynamic configurations. Here are the three methods: 

1. Using the environment Section

The environment section in a docker-compose.yml file allows you to define environment variables directly within the service. 

Example:

version: ‘3’

services:

  app:

    image: my-app

    environment:

      – APP_ENV=production

      – DATABASE_URL=mysql://user:password@db:3306/mydatabase

2. Using an .env File

A more secure and flexible approach is to use an .env file to store environment variables separately. Docker Compose automatically loads the variables from this file.

Example:

.env file

APP_ENV=production

DATABASE_URL=mysql://user:password@db:3306/mydatabase

docker-compose.yml file

version: ‘3’

services:

  app:

    image: my-app

    env_file:

      – .env

3. Passing Variables from the Host System

Docker Compose allows you to pass environment variables from the host machine to the container dynamically.

Example:

Run the following command in the terminal before running docker-compose up:

export APP_ENV=production

export DATABASE_URL=mysql://user:password@db:3306/mydatabase

docker-compose up

Alternatively, use placeholders in docker-compose.yml:

version: ‘3’

services:

  app:

    image: my-app

    environment:

      – APP_ENV=${APP_ENV}

      – DATABASE_URL=${DATABASE_URL}

How to View Docker Environment Variables

To check the Docker environment variables inside a running container, you can use multiple methods, such as: 

1. Using the env Command

Run the following command to view all environment variables inside a running container:

docker exec -it <container_id> env

Example:

docker exec -it my-container env

2. Using the printenv Command

Another way to list environment variables inside a container is:

docker exec -it <container_id> printenv

3. Inspecting a Container’s Environment Variables

To check environment variables without accessing the container, use:

docker inspect <container_id>

This returns a JSON output. To filter only environment variables:

docker inspect –format='{{range .Config.Env}}{{println .}}{{end}}’ <container_id>

Using Environment Variables with docker run

When you are running a Docker container, you can pass Docker environment variables dynamically with the -e flag. 

1. Passing a Single Variable

docker run -e APP_ENV=production my-app

Inside the container, APP_ENV will be available for production.

2. Passing Multiple Variables

docker run -e APP_ENV=production -e DB_USER=root -e DB_PASS=secret my-app

3. Using an .env File

Instead of passing all the variables manually, you can use an .env file. 

Example .env file:

APP_ENV=production

DB_USER=root

DB_PASS=secret

Run the container with:

docker run –env-file .env my-app

Best Practices for Managing Docker Environment Variables

Managing Docker compose environment variables effectively ensures reliable security, maintainability, and flexibility. Here are some of the best practices to follow: 

Best Practice	Description	Example/Implementation
Use an .env File for Configuration	Store environment variables separately to keep docker-compose.yml clean.	Define variables in an .env file and reference it in docker-compose.yml.
Avoid Storing Sensitive Data in Dockerfiles	Prevent hard coded credentials in Docker images.	Use ENV for non-sensitive values and external secrets management tools for sensitive data.
Use docker run –env-file for Secure Deployment	Prevents exposure of credentials in terminal history.	docker run –env-file .env my-app
Use the Least Privilege Principle	Define only necessary environment variables to reduce security risks.	Avoid exposing system-wide variables unless required.
Keep Environment Variables Consistent Across Environments	Use separate .env files for different environments.	.env.dev for development, .env.prod for production.
Use Docker Secrets for Sensitive Data	For production, store passwords and API keys securely.	docker secret create my_secret secret.txt

Conclusion

Docker compose environment variables provide a powerful means to configure applications dynamically. By implementing these strategies, you can efficiently manage environment variables within the containers. This ensures a more robust Docker-based application deployment.