Beginner’s Guide to Environment Variables with Docker

Wed, 20 Aug 2025 05:52:51 +0000

If you’ve ever worked with Docker, you’ve probably heard the term “environment variables”. They play an important role in configuring your containers and securing your sensitive data. This guide will walk you through everything you need to know about using environment variables with Docker Compose, even if you’re a complete beginner.

???????? What Are Environment Variables?
Environment variables are key-value pairs used to configure applications. Instead of hard-coding values (such as passwords or database URLs), you can store them as variables and access them from your code.

For example:

DATABASE_URL=mongodb://localhost:27017/mydb

API_KEY=9YmCCoJfsI9sIactxPBu

???? Why Use Environment Variables in Docker Compose?

When you’re using Docker Compose to spin up multi-container applications, environment variables help you:

Avoid hardcoding sensitive data in your docker-compose.yml
Easily switch between development, staging, and production setups
Keep your configuration clean and reusable

???? Ways to Set Environment Variables in Docker

1. Using the environment attribute
You can set variables inline in your docker-compose.yml file:

services:

web:

image: node:23.11.0
environment:
  - NODE_ENV=development
  - PORT=5000
  - API_KEY=PLdaTwF9YmCCoJfsI9sIactxPBu

⚠️ This method is simple, but can expose sensitive data.

Using an .env file as the best practice

Create a .env file in the same directory as your docker-compose.yml:

PORT=5000
NODE_ENV=development
API_KEY=PLdaTwF9YmCCoJfsI9sIactxPBu

Then in your docker-compose.yml:

services:
web:
 image: node:23.11.0
 ports:
  - "${PORT}:5000"
 environment:
  - NODE_ENV=${NODE_ENV}
  - API_KEY=${API_KEY}

✅ Docker Compose automatically loads .env from the same directory.

2. Using env_file attribute to load variables
You can also explicitly tell Docker Compose to use a specific .env file:

services:
web:

image: node:23.11.0
env_file:
  - ./dev.env

This allows configurations to be separated according to the
environment. (e.g., dev.env, prod.env).

3. Using shell environment variables
You can export environment variables in your terminal before running Docker Compose:

export NODE_ENV=development
export PORT=3000
docker-compose up

4. Passing variables inline when running a container (less common in Compose)
This approach is more common with docker run, but worth noting:

docker run -e NODE_ENV=production node:23.11.0

In Docker Compose, this is equivalent to setting them under
environment:.

???????????? Bonus: Environment Variables vs Build Arguments
Build arguments are similar to environment variables, but they’re used at build time instead of runtime.

Example: Using ARG in Dockerfile

FROM node:23.11.0
ARG NODE_ENV
RUN echo "Building in $NODE_ENV mode"

Set ARG in docker-compose.yml

services:

web:

build:
  context: .
  args:
    NODE_ENV: development

Key differences:

ARG is only available during the image build process.
ENV (environment variable) is available at container runtime.
If you need a variable during the build, use ARG. If your app needs it during runtime, use ENV.

???? Best Practices
⚡ Never commit .env files with secrets to version control.

????️ Use different .env files for different environments.
✅ Keep your .env file in the same folder as docker-compose.yml for auto-detection.

???? Debug Tip
Want to make sure your variables are loaded? Run this:

docker-compose exec web env

This shows all environment variables inside the running container.

If you would like to improve your skills, please check out my other articles on docker and docker-compose on different subjects:

How to Deploy ReactApp to AWS EC2 with docker, nginx and automate with gitHubAction.

✨ Final Thoughts
Environment variables make Docker Compose setups more secure, cleaner, and easier to manage. Whether you’re running a single service or a complex app with multiple containers, mastering environment variables is a foundational skill that pays off.

Thanks for reading through and I hope you liked what you read here. Feel free to connect with me on LinkedIn, twitter and GitHub.

Happy Dockering! ????

Coder Legion - Recent posts tagged env

Beginner’s Guide to Environment Variables with Docker