Environment Files & Secrets

Introduction

Compose reads .env from the project root and substitutes ${VAR} in the YAML. Use it for non-secret config. For real secrets use Docker secrets or a manager (Vault, AWS SSM).

Purpose of this lesson

This lesson teaches Environment Files & Secrets as an engineering decision: what problem it solves, when to use it, how to implement it safely, and what signals tell you it is failing.

Understanding the topic

Use this in production readiness work. These practices decide whether containers are merely running or are actually secure, observable, recoverable, and safe to promote through a delivery pipeline.

Core concepts to understand:

• .env = KEY=value per line, loaded automatically.
• env_file: in a service loads vars into the container.
• environment: sets explicit vars in YAML.
• Never commit secrets — add .env to .gitignore.

Visual explanation

Architecture or command flow to keep in mind:

# .env
DB_PASSWORD=devsecret

# compose.yml
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}

Step-by-step explanation

1. Start from a trusted, pinned base image and document why it fits the runtime.
2. Order Dockerfile instructions from least-changing dependency metadata to most-changing source files so the cache stays useful.
3. Build locally with BuildKit, inspect layers with docker history, and run the image with the same command CI will use.
4. Test shutdown behavior, health checks, non-root execution, and runtime configuration before pushing the image.
5. Tag with an immutable version or git SHA, scan the image, and promote the same artifact through environments.

Informative example

Use the example below as a working baseline, then verify the runtime behavior instead of assuming the command or file is correct.

# .env
DB_PASSWORD=devsecret

# compose.yml
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}

A production-minded check usually includes docker ps, docker logs, docker inspect, and one validation from outside the container such as curl, a database connection, or a registry pull.

# Verification loop for Environment Files & Secrets
docker ps -a
docker logs --tail=100 <container-name>
docker inspect <container-or-image-name>
docker system df

Real-world use

Most teams ship a .env.example in git and ask devs to copy/fill .env locally. Production reads from the secret manager, not files.

Enterprise use cases

In a mature engineering organization, Environment Files & Secrets is documented as a repeatable pattern with approved base images, ownership labels, CI checks, security expectations, rollback notes, and troubleshooting commands. The difference between a tutorial and production practice is that every container decision must be observable, reviewable, and reversible.

Best practices

• Commit .env.example; ignore .env.
• Use Docker secrets or external KMS for prod credentials.

Common mistakes

• Committing .env by accident — rotate the leaked secrets immediately.

Debugging tips

• Use docker build --progress=plain when BuildKit output hides the failing build step.
• Run the image with a temporary shell or overridden command to inspect files, users, environment, and entrypoint behavior.
• Check docker history for accidental secrets, unexpectedly large layers, and cache-busting instructions.

Optimization strategies

• Treat image size, CVE count, non-root execution, and digest pinning as release quality signals.
• Set log rotation and resource limits before the first production incident, not after disk or memory exhaustion.
• Cache builds by registry or CI cache backend while still scanning the final pushed image.

Advanced interview questions

Hands-on exercise

Create a small lab for Environment Files & Secrets: run the example, inspect the created Docker object, intentionally introduce one mistake, and record the command that reveals the failure. The goal is not just to make the happy path work; it is to build operational reflexes.

# Hands-on lab scaffold
mkdir -p docker-environment-files-secrets-lab
cd docker-environment-files-secrets-lab

# Add the Dockerfile, compose.yml, or command from this lesson.
# Then run one happy-path test and one broken-path test.
docker version
docker info
docker system df

Summary

Environment Files & Secrets matters because Docker is not only a packaging tool; it is a runtime, build, networking, storage, and delivery workflow. Treat each lesson as a production habit: make it repeatable, inspectable, secure, and easy to debug.