LATEST 🚀 Welcome to Upgradix by Shrash Studio – Your destination for free technology learning and career growth.
🕘 Updated:
Docker

Environment Variables and Secrets in 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.

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.

What you will learn
  • Why hardcoding configurations is a bad architectural practice.
  • How to use .env files to pass variables safely into Docker Compose.
  • The difference between the environment block and the env_file directive.
  • 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...
Important: Always add .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

.env File Local Secrets Docker Compose Interpolates YAML Container OS Environment Variables Active

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.

Step 1: Reading the Environment Docker automatically searches the directory where you ran the command for a file named exactly .env. If it finds it, it loads all the key-value pairs into its own memory.
Step 2: YAML Interpolation Docker parses your 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.
Step 3: Container Injection Docker interacts with the container runtime (like containerd) to spin up the actual isolated Linux process. It takes the final, computed values and passes them as true OS-level environment variables to the new container.
Watch out: Do not confuse the .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.

Beginner Exercise 1: Hide your API Key

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.

Intermediate Exercise 2: Command Line Overrides

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.

Advanced Exercise 3: Upgrading to Docker Secrets

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.

Q1. What is the difference between an `.env` file and the `env_file:` directive in Docker Compose?

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.

Q2. How would you securely pass a production database password into a Docker container without committing it to version control?

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

Upgradix by Shrash Studio – Learn Technology. Build Your Future.

Comments & Ratings (0)

Log in or create a student account to comment and rate this article.

Be the first to comment on this article.