Docker Environment Variables and Secrets

# CHAPTER 12

Docker Environment Variables and Secrets #

1. Introduction #

2. Learning Objectives #

• Understand the 12-Factor App methodology regarding configuration.

• Inject Environment Variables via the Docker CLI (-e flag).

• Centralize variables using an .env file with Docker Compose.

• Prevent hardcoded secrets from entering Version Control.

• Understand the conceptual basics of Docker Secrets in Swarm/Kubernetes.

3. Beginner-Friendly Explanation #

• Hardcoding (Dangerous): You engrave the missile launch codes directly onto the dashboard. If the enemy steals the car, they instantly have the launch codes.

• Environment Variables (Secure): The dashboard has a blank slot. When the spy (The Environment) gets into the car, they insert a temporary smart-key containing the codes into the slot. When the spy leaves the car, they take the key with them. The car remains functional, but the secrets are never permanently attached to it.

4. The ENV Instruction in Dockerfiles #

FROM node:18-alpine
ENV PORT=3000
ENV NODE_ENV=production
COPY . /app
CMD ["npm", "start"]

These are excellent for defining *non-sensitive* default application settings, ensuring the container knows it should run in "production" mode on port 3000 by default.

5. Overriding via the CLI (-e) #

docker run -e PORT=8080 -e API_KEY=xyz123 my-node-app

*Problem:* Typing secrets directly into the terminal is bad practice. Terminal histories (like ~/.bash_history) record every command you type, meaning your API key is now saved in plain text on your hard drive!

6. The .env File and Docker Compose #

1. 1. You create a simple text file named .env in the same directory as your docker-compose.yml.

1. 2. Inside .env, you define your secrets:

DATABASE_PASSWORD=supersecret99
STRIPE_API_KEY=sk_live_12345

1. 3. In your docker-compose.yml, you reference these variables using ${VARIABLE_NAME} syntax:

services:
  db:
    image: mysql:8.0
    environment:
      - MYSQL_ROOT_PASSWORD=${DATABASE_PASSWORD}
  web:
    image: php:8.2-apache
    environment:
      - STRIPE_KEY=${STRIPE_API_KEY}

When you run docker-compose up, Compose silently reads the .env file, injects the secrets into the containers, and launches the application perfectly.

7. Mini Project: Secure Application Configuration #

Step-by-Step Tutorial:

1. 1. Create a folder named secure-app.

1. 2. Crucial First Step: Create a .gitignore file and type .env inside it. *This ensures you never accidentally push your passwords to GitHub!*

1. 3. Create the .env file:

APP_THEME=dark_mode

1. 4. Create an index.php file that reads the variable:

<?php
$theme = getenv(&#039;APP_THEME');
echo "<h1>The application is running in: $theme</h1>";
?>

1. 5. Create docker-compose.yml:

version: '3.8'
services:
  web:
    image: php:8.2-apache
    ports:
      - "8000:80"
    volumes:
      - ./:/var/www/html
    environment:
      - APP_THEME=${APP_THEME}

1. 6. Run docker-compose up -d. Check http://localhost:8000. It will display "dark_mode".

1. 7. Edit the .env file to say APP_THEME=light_mode. Run docker-compose up -d again. Docker automatically detects the environment change and updates the running container securely!

8. Real-World Scenarios #

9. Best Practices #

• Provide a .env.example file: Because you .gitignore the real .env file, new developers cloning your repository won't know what variables the app needs! Always commit a .env.example file containing dummy data (e.g., DB_PASSWORD=your_password_here). The developer copies the example file, renames it to .env, and fills in their real passwords.

10. Common Mistakes #

• Hardcoding Secrets in the Dockerfile: Never use the ENV or ARG instructions in a Dockerfile to bake passwords into the image. Anyone who pulls your image from Docker Hub can run docker inspect <image_name> and read your passwords in plain text! Passwords must only be injected at runtime.

11. Exercises #

1. 1. What is the fundamental security reason for adding the .env file to your project's .gitignore list?

1. 2. Contrast the use-case for utilizing the ENV instruction within a Dockerfile versus injecting variables at runtime via a docker-compose.yml file.

12. FAQs #

13. Interview Questions #

• Q: Explain the 12-Factor App principle regarding "Config." Why is it an anti-pattern to store database credentials within application configuration files (e.g., a PHP config.php file) committed to version control?

• Q: An auditor discovers that a developer has baked an AWS API key into a custom Docker image using the ENV instruction in the Dockerfile. Explain why this is a critical security breach and detail the architectural changes required to resolve it.

14. Summary #

15. Next Chapter Recommendation #