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:
✨ 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! ????