Environment Variables and Secrets in Docker Compose
When you build modern applications, your code has to run in multiple places: your local laptop, a staging server, and a live production environment. In each of these places, the application needs different configuration details, like database passwords, API keys, and server port numbers.
If you hardcode these sensitive details directly into your application code or your docker-compose.yml file, you are creating a massive security risk. Anyone who can read your code can steal your database password. To solve this, Docker Compose gives us powerful tools to inject Environment Variables and Secrets directly into our running containers from the outside.
- Why hardcoding configurations is a bad architectural practice.
- How to use
.envfiles to pass variables safely into Docker Compose. - The difference between the
environmentblock and theenv_filedirective. - How to manage highly sensitive data using Docker Secrets.
1. The Problem with Hardcoded Configurations
Imagine you are building a .NET Core API or a Python Django app that connects to a PostgreSQL database. If you type the database password directly into your Docker Compose file, you must commit that file to GitHub or your version control system so your team can use it. Now, your production database password is permanently stored in your code history.
By using environment variables, we separate the code from the configuration. The code stays the same everywhere, but the configuration changes depending on where the code is running.
| Method | How it works | When to use it |
|---|---|---|
environment attribute |
Defines variables directly inside the docker-compose.yml file. |
For non-sensitive settings like NODE_ENV=development or PORT=8080. |
.env file (Interpolation) |
Variables are placed in a hidden .env file. Compose reads them and substitutes them into the YAML file using ${VAR_NAME}. |
For passwords, API keys, and connection strings. Never commit this file to version control. |
| Docker Secrets | Docker mounts a secure, read-only file directly into the container's memory at runtime (usually in /run/secrets/). |
For highly regulated enterprise environments, production clusters (Docker Swarm/Kubernetes), and extreme security. |
2. Practical Implementation & Code
Let's look at how to properly secure a PostgreSQL database connection using a .env file. We will create two files in the same folder: .env and docker-compose.yml.
Step A: Create the .env file
Example 1: .env (Do not commit this file to Git!)
# Database Configuration
POSTGRES_USER=admin_upgradix
POSTGRES_PASSWORD=SuperSecretPassword2026!
APP_PORT=5000
Step B: Write the Docker Compose file
Now, we use the ${VARIABLE_NAME} syntax inside our YAML file. When we run the docker compose up command, Docker will automatically look for the .env file, grab the values, and replace the placeholders before starting the container.
Example 2: docker-compose.yml
services:
database:
image: postgres:15-alpine
container_name: my_secure_db
restart: always
environment:
# Injecting secrets from the .env file into the container
POSTGRES_USER: ${POSTGRES_USER}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
ports:
- "5432:5432"
web_api:
image: my_api_image:latest
ports:
- "${APP_PORT}:80"
environment:
# We can also pass a connection string built dynamically
DB_CONNECTION: "Host=database;Username=${POSTGRES_USER};Password=${POSTGRES_PASSWORD}"
depends_on:
- database
Checking your configuration
Before you start your containers, you can verify that Docker is reading your .env file correctly by running a simple command.
$ docker compose config
# Output shows the YAML with the actual values injected:
services:
database:
environment:
POSTGRES_PASSWORD: SuperSecretPassword2026!
POSTGRES_USER: admin_upgradix...
.env to your .gitignore file immediately. If you accidentally commit a password to GitHub, you must consider it compromised and change it immediately.3. Architecture / Workflow Visualized
Understanding how Docker Compose processes these variables under the hood is critical for debugging. It does not just copy the file; it performs an active interpolation process.
How Docker Compose Injects Environment Variables
Docker Compose acts as the middleman. It reads the local .env file, substitutes the values into your YAML file, and then passes those raw values directly into the container's operating system environment.
4. Step-by-Step Execution Breakdown
When you type docker compose up -d, a very specific sequence of events occurs regarding your variables.
.env. If it finds it, it loads all the key-value pairs into its own memory.docker-compose.yml file. Every time it sees a ${VARIABLE_NAME} syntax, it swaps out that text for the actual value it loaded in Step 1..env file (which Docker Compose uses to do text-replacement in the YAML file) with the env_file: directive in a Compose file (which takes a file and blindly dumps every variable inside it straight into the container). If you use env_file:, you cannot use those variables for things like port mapping in your YAML!5. Hands-On Practice
The best way to understand this architecture is to build it. Try these exercises on your local machine.
Create a basic Node.js, Python, or .NET container. Hardcode an API key in your YAML file using the environment block. Then, extract it. Move the key to a .env file and update your YAML to use ${API_KEY}.
Hint: Use docker compose config to verify that the replacement worked before starting the container.
Did you know you can override the .env file directly from your terminal? Run your compose file but inject a different port via the command line.
Expected result: If your .env file says APP_PORT=5000, try running APP_PORT=8080 docker compose up -d. The terminal variable will win, and the app will bind to 8080.
For true production readiness, skip the .env file entirely. Research how to use the top-level secrets: block in your docker-compose.yml file to pass a text file directly into the container's /run/secrets/ directory.
Hint: Many official database images, like Postgres and MySQL, support variables ending in _FILE (e.g., POSTGRES_PASSWORD_FILE). This tells the database to read the password from the secret file path rather than standard environment variables.
6. Interview Questions
If you are applying for a Backend Developer, DevOps, or Software Architect role, interviewers will heavily test your knowledge of container security and configuration management.
Answer: An .env file is read by the Docker Compose CLI before the containers start. It is used to substitute variables (like ${PORT}) inside the docker-compose.yml file itself. The env_file: directive is a command inside the YAML file that tells Docker to take a specific text file and push all the variables inside it directly into the container's runtime environment. Variables in an env_file cannot be used to configure Compose settings like ports or volume paths.
Answer: The most standard approach for local or simple deployments is to define the password in a local .env file, ensure that file is added to .gitignore, and use interpolation in the Compose file to pass it to the environment block. For enterprise production, I would not use environment variables at all; I would use Docker Secrets (or a tool like AWS Secrets Manager / HashiCorp Vault) to mount the password as an in-memory, read-only file at runtime, as environment variables can sometimes be leaked in crash logs or via the docker inspect command.
Conclusion
Managing configuration effectively is one of the most critical skills for a modern software architect. By extracting your passwords, API keys, and environment-specific settings out of your code and into .env files, you make your applications safer, more portable, and much easier to deploy across multiple servers.
Always remember the golden rule of configuration: Code should be public; configuration must be private. Master these Docker Compose variable techniques, and you will build a robust foundation for automated, secure CI/CD pipelines.
Official Documentation
- Docker Documentation – Set environment variables in Compose
- Docker Reference – Use secrets in Docker Compose
Upgradix by Shrash Studio – Learn Technology. Build Your Future.