Introduction
When building modern applications using Docker, managing configuration properly becomes very important. Many developers make the mistake of hardcoding values like database credentials, API URLs, or secret keys directly into the application code. This approach creates problems when you move your application between environments such as development, testing, and production.
Docker environment variables solve this problem in a clean and scalable way. They allow you to pass configuration values into your container at runtime without changing your code. This makes your application flexible, secure, and easy to maintain.
What are Environment Variables in Docker?
Understanding the Basics
Environment variables in Docker are simple key-value pairs that are passed into a container. These variables are used by your application to control behavior without modifying the actual code.
For example, instead of writing a database URL inside your code, you can store it as an environment variable and read it when the application runs.
Real-Life Examples
Here are some common use cases:
Database connection string (DB_HOST, DB_USER, DB_PASS)
API endpoints (API_URL)
Application mode (development, staging, production)
Secret keys and tokens
This approach is widely used in cloud environments and containerized applications.
Why Use Environment Variables in Docker?
Flexibility Across Environments
One of the biggest advantages of Docker environment variables is that you can use the same Docker image in multiple environments. You only change the variables, not the code.
Improved Security
Sensitive data like passwords and API keys should never be hardcoded. Using environment variables helps keep this data separate from your source code.
Easy Configuration Management
You can quickly update configuration values without rebuilding your Docker image.
Better Portability
Your Docker container becomes portable because it does not depend on fixed values. It can run anywhere with different configurations.
Method 1: Using ENV in Dockerfile
What is ENV?
The ENV instruction in a Dockerfile is used to define environment variables during the image build process.
Example Dockerfile
FROM node:18
ENV APP_ENV=production
ENV API_URL=https://api.example.com
WORKDIR /app
COPY . .
RUN npm install
CMD ["npm", "start"]
Explanation in Simple Words
ENV sets default values inside the Docker image
These values are available whenever the container starts
If you do not override them, these values will be used
When to Use This Method
Use ENV when you want to set default values that rarely change.
Method 2: Passing Environment Variables using docker run
Runtime Configuration
You can pass environment variables when starting a container using the docker run command.
Example Command
docker run -e APP_ENV=development -e API_URL=https://dev.api.com my-app
Explanation in Simple Words
The -e flag allows you to define variables at runtime
These values override Dockerfile ENV values
Useful for testing and switching environments quickly
When to Use This Method
This method is best for quick changes and temporary configurations.
Method 3: Using an .env File
What is an .env File?
An .env file is a simple text file where you store multiple environment variables in one place.
Example .env File
APP_ENV=development
API_URL=https://dev.api.com
DB_HOST=localhost
DB_USER=root
DB_PASS=secret
Running with .env File
docker run --env-file .env my-app
Explanation in Simple Words
Instead of writing multiple -e flags, you use a file
Easier to manage and organize configuration
Commonly used in local development setups
Benefits
Method 4: Using Docker Compose
What is Docker Compose?
Docker Compose is a tool used to define and run multi-container Docker applications.
Example docker-compose.yml
version: '3.8'
services:
app:
image: my-app
ports:
- "3000:3000"
environment:
- APP_ENV=production
- API_URL=https://api.example.com
Using Variables from .env
environment:
- APP_ENV=${APP_ENV}
- API_URL=${API_URL}
Explanation in Simple Words
You can define variables directly or use placeholders
Docker Compose automatically reads from a .env file
Ideal for complex applications with multiple services
When to Use Docker Compose
Use it when working with microservices or full-stack applications.
Method 5: Difference Between ARG and ENV
Understanding ARG (Build-Time Variable)
ARG is used during the image build process and is not available after the image is created.
Understanding ENV (Runtime Variable)
ENV is available when the container is running.
Example
ARG APP_VERSION=1.0
ENV APP_ENV=production
Simple Explanation
Key Tip
Do not use ARG for sensitive runtime data because it will not be available inside the container.
Best Practices for Docker Environment Variables
Avoid Hardcoding Sensitive Data
Never store secrets like passwords in Dockerfile or code.
Use .env Files for Development
This keeps your configuration organized and easy to manage.
Use Secret Managers in Production
For production environments, use tools like AWS Secrets Manager or Kubernetes Secrets.
Keep Naming Consistent
Use clear and consistent naming like APP_ENV, DB_HOST, API_URL.
Separate Configuration from Code
Always keep configuration outside your application code.
Real-World Example: Node.js Application
Dockerfile
FROM node:18
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
CMD ["node", "server.js"]
Application Code
const express = require('express');
const app = express();
const PORT = process.env.PORT || 3000;
const ENV = process.env.APP_ENV || 'development';
app.get('/', (req, res) => {
res.send(`Running in ${ENV} mode on port ${PORT}`);
});
app.listen(PORT, () => {
console.log(`Server running on port ${PORT}`);
});
Run Command
docker run -e PORT=4000 -e APP_ENV=production -p 4000:4000 my-node-app
What Happens Here?
The container receives PORT and APP_ENV
The app reads values using process.env
Behavior changes without modifying code
Common Mistakes to Avoid
Hardcoding Secrets
This is a major security risk and should always be avoided.
Not Using .env Files
Managing many variables manually can become messy.
Confusing ARG and ENV
Using the wrong type of variable can break your configuration.
Ignoring Environment Differences
Always configure separate values for development, staging, and production.
Summary
Configuring environment variables in Docker containers is a fundamental skill for building modern, scalable, and secure applications. By using Docker ENV, docker run variables, .env files, and Docker Compose, you can manage configuration efficiently without changing your code. This approach improves flexibility, enhances security, and makes your application ready for real-world deployment. If you follow best practices and avoid common mistakes, your Docker-based applications will be clean, portable, and production-ready.