Reading App Config & .env Files

env_file reads a file of KEY=VALUE pairs and injects them as environment variables at runtime — not at build time.

When Docker Compose starts the container, it reads the specified file (here .env) line by line and sets each KEY=VALUE pair as an environment variable inside the running container. The file itself is NOT copied into the image.

Key distinctions:

• env_file: → injects ALL variables from a file into the container environment
• environment: → injects individual named variables (can inline values or reference host env)
• volumes: - .:/app → mounts the current directory into /app (this mounts the .env file on disk, but that is separate from loading it as environment variables)

.env file format:

DATABASE_URL=postgres://user:pass@db:5432/myapp
NODE_ENV=production
SECRET_KEY=abc123

Security note: Never commit your .env file to version control. Add it to .gitignore. Use a .env.example file with placeholder values as documentation for other developers.

Vocabulary:

• env_file → Docker Compose directive to load environment variables from a file
• runtime → when the container is actually running (vs. build time when the image is created)
• inject → pass a value into a process without hardcoding it in the code

Never commit a .env file that contains real secrets to version control.

This file contains highly sensitive values:

• STRIPE_SECRET_KEY=sk_live_abc123xyz → a live payment API key. Anyone who reads this can charge customers and access financial data.
• DATABASE_URL=postgresql://admin:s3cr3t@... → full database credentials including password and host.

Why "private repository" is NOT a safe answer: Repositories get inadvertently made public, team members leave, access tokens are leaked, and git history is permanent — even if you delete the file later, it remains in the commit history forever.

The correct pattern:

• Add .env to .gitignore to prevent accidental commits
• Commit a .env.example file with placeholder values: STRIPE_SECRET_KEY=your_stripe_key_here
• Store real secrets in a secrets manager (AWS Secrets Manager, HashiCorp Vault, GitHub Actions Secrets)
• On servers, inject secrets via CI/CD environment variables, never via committed files

Vocabulary:

• secret → a credential or API key that must be kept confidential
• .gitignore → a file listing paths that git should not track
• secrets manager → a service for securely storing and retrieving credentials at runtime
• placeholder → a dummy value showing the expected format without exposing the real value

Docker networks allow containers to communicate by service name without exposing ports to the host.

When two services share the same network (here backend), Docker provides built-in DNS resolution. The api service can connect to the database using the hostname db (the service name) on PostgreSQL's default internal port 5432:

DATABASE_URL=postgres://user:pass@db:5432/mydb

Port mapping clarification:

• ports: "HOST:CONTAINER" → exposes the container port to your laptop/server (so you can connect from outside Docker)
• No ports: → the service is only reachable from within the Docker network (other containers on the same network). This is more secure for databases — you don't want PostgreSQL exposed to the internet.

Named volumes (uploads, pgdata):

• Persist data beyond container restarts
• Managed by Docker — stored outside the container filesystem
• Contrast with bind mounts (./local-dir:/container-dir) which map to a specific host directory

Vocabulary:

• Docker network → an isolated virtual network connecting containers
• service name DNS → Docker resolves container hostnames by service name within a network
• named volume → a persistent Docker-managed storage volume
• expose vs. publish → expose makes a port visible within the network; publish (ports:) maps it to the host

<<: *default is a YAML merge key — it copies all entries from the default anchor into the current mapping.

YAML anchors and aliases:

• &default → creates an anchor named "default" on this mapping. It stores all the key-value pairs at that level.
• *default → an alias — a reference to the anchor. Using it alone would just reference the same object.
• <<: *default → a merge key. It deep-merges the referenced anchor's key-value pairs into the current mapping. Child keys can override merged ones.

Reading the production block:
The production environment inherits: adapter: postgresql, encoding: unicode, timeout: 5000 from *default. Then it overrides pool (to 20 default instead of 5) and adds url.

The <%= ENV['DATABASE_URL'] %> syntax: This is ERB (Embedded Ruby) — it reads an environment variable at runtime and substitutes the value. In production, the database URL comes from the environment, not a hardcoded value.

Vocabulary:

• anchor (&name) → marks a YAML node for reuse
• alias (*name) → references a previously defined anchor
• merge key (<<:) → merges the referenced mapping into the current one
• ERB → Embedded Ruby; template syntax that evaluates Ruby expressions in config files

Variables without a value are "pass-through" variables — Docker reads them from the host environment.

When you write - SENTRY_DSN (no equals sign), Docker Compose looks up SENTRY_DSN in the shell environment where you run docker compose up. If the variable exists on the host, its value is injected into the container. If it does not exist on the host, the variable is not set inside the container (it does not default to empty string).

Why this pattern is useful:

• Keeps sensitive values out of the docker-compose.yml file entirely (no values hardcoded)
• The compose file can be committed to version control safely
• Each developer or server exports their own values: export DATABASE_URL=postgres://...
• In CI/CD, secrets are configured as pipeline environment variables and pass through automatically

The three ways to set env vars in Compose:

• KEY=value → hardcoded value (visible in the file — avoid for secrets)
• KEY → pass-through from host environment
• env_file: .env → load all variables from a file

Vocabulary:

• pass-through variable → a variable whose value is inherited from the outer (host) environment
• host environment → the shell session or CI system where Docker Compose runs
• inject → supply a value to a process at runtime rather than embedding it in code