Environment Variables in Docker Compose: The Complete Beginner’s Guide

When working with Docker Compose, using environment variables is one of the best ways to make your configuration dynamic, reusable, and secure.

In this blog, you’ll learn:

• 💡 What are environment variables?
• 🧩 How to use them in Docker Compose
• 📁 The role of .env files
• 🧪 Real-world examples
• ✅ Best practices to keep things clean and secure

Let’s get started!

💡 What Are Environment Variables?

Environment variables are key-value pairs used to store configuration settings. They let you define data like:

• Database names and passwords
• API keys
• Port numbers
• Paths
• Environment types (e.g., development, production)

This helps you avoid hardcoding sensitive or changing values directly into your code or Docker Compose file.

⚙️ Using Environment Variables in docker-compose.yml

Docker Compose allows you to use environment variables by referencing them with ${} syntax.

✅ Example

version: '3.9'

services:
  web:
    image: "nginx:${NGINX_VERSION}"
    ports:
      - "${APP_PORT}:80"
    environment:
      - APP_ENV=${APP_ENV}
      - API_KEY=${API_KEY}

Here:

• NGINX_VERSION, APP_PORT, APP_ENV, and API_KEY are environment variables.
• Docker Compose will look for these in your system environment or a .env file.

📁 Using a .env File

Docker Compose automatically looks for a file named .env in the same directory as your docker-compose.yml.

✅ .env Example

NGINX_VERSION=latest
APP_PORT=8080
APP_ENV=development
API_KEY=12345-abcdef

🔁 Now you can run:

docker-compose up

Docker Compose will automatically inject the values from .env.

🧪 Real-World Example

docker-compose.yml

version: '3.9'

services:
  app:
    build:
      context: .
      args:
        NODE_ENV: ${NODE_ENV}
    environment:
      - NODE_ENV=${NODE_ENV}
    ports:
      - "${APP_PORT}:3000"
    volumes:
      - .:/app

.env

NODE_ENV=development
APP_PORT=3000

📤 Injecting Environment Variables via CLI

You can also pass environment variables inline when running Docker Compose:

NODE_ENV=production APP_PORT=8080 docker-compose up

These will override what's in your .env file or system.

🧪 Using env_file in Compose

If you want to load variables into a service’s container, use the env_file property.

Example

services:
  app:
    image: myapp
    env_file:
      - ./app.env

app.env

DB_HOST=db
DB_USER=root
DB_PASS=password

📝 This file is loaded into the container’s environment, not the Compose file itself.

🧠 Key Differences

✅ Best Practices

🔒 Keep .env files out of version control
Use .gitignore to avoid committing secrets:

.env
*.env

🧹 Use defaults in your Compose file

ports:
  - "${APP_PORT:-8000}:80"

🛠️ Use docker-compose config to debug
Run this to see the final file after variable substitution:

docker-compose config

🧠 Summary

🚀 Final Thoughts

Using environment variables in Docker Compose is a simple but powerful way to:

• Make your setup environment-independent
• Keep secrets out of your Compose file
• Customize behavior for dev, staging, or prod
• Follow 12-Factor App principles

Try replacing some of your hardcoded values with ${} variables today — your future self will thank you! 🙌