Why process.env Variables Are Undefined in Docker (And How to Fix It)

# Dockerfile
FROM node:20-alpine

WORKDIR /app

# Set safe non-secret defaults with ENV
ENV PORT=3000     NODE_ENV=production     LOG_LEVEL=info     CACHE_TTL=3600

COPY package*.json ./
RUN npm ci --omit=dev

COPY . .

EXPOSE 3000

# Healthcheck using the PORT env var
HEALTHCHECK --interval=30s --timeout=5s   CMD wget -qO- http://localhost:${PORT}/health || exit 1

CMD ["node", "server.js"]

# Your Node.js server — process.env.PORT is available
const express = require('express');
const app = express();

const PORT = process.env.PORT || 3000; // Gets 3000 from the ENV directive
const NODE_ENV = process.env.NODE_ENV; // Gets 'production' from ENV

app.get('/health', (req, res) => {
  res.json({ status: 'ok', env: NODE_ENV, port: PORT });
});

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT} in ${NODE_ENV} mode`);
});

# Your local .env file (stays on host, never in image)
DATABASE_URL=postgresql://user:secret@localhost/mydb
REDIS_URL=redis://localhost:6379
STRIPE_SECRET_KEY=sk-test-YOUR_KEY
JWT_SECRET=my-super-secret-key
API_BASE_URL=http://localhost:8080

# Build the image (no secrets baked in)
docker build -t myapp .

# Run with env file — Docker reads .env from current directory
docker run --env-file .env -p 3000:3000 myapp

# Or pass specific env file paths
docker run --env-file ./config/.env.staging -p 3000:3000 myapp

# Mix: env file + individual overrides
docker run   --env-file .env   -e NODE_ENV=production   -e LOG_LEVEL=debug   -p 3000:3000   myapp

# Verify variables are set inside the running container
docker exec <container_id> printenv DATABASE_URL

# docker-compose.yml
version: '3.9'

services:
  app:
    build: .
    ports:
      - "3000:3000"

    # Method A: env_file — reads the file and injects all variables
    env_file:
      - .env                    # loads base variables
      - .env.development        # loads dev overrides (if exists)

    # Method B: environment — explicit key=value or variable substitution
    environment:
      - NODE_ENV=development

      # Variable substitution: reads from host shell environment
      - DATABASE_URL=${DATABASE_URL}

      # Or set literal values directly
      - REDIS_URL=redis://redis:6379
      - LOG_LEVEL=debug

    depends_on:
      - db
      - redis

  db:
    image: postgres:16-alpine
    environment:
      - POSTGRES_DB=myapp_dev
      - POSTGRES_USER=myuser
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}  # from host env or .env
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    command: redis-server --requirepass ${REDIS_PASSWORD}

volumes:
  postgres_data:

# .env (in the same directory as docker-compose.yml)
# Docker Compose automatically reads this file for variable substitution
# in the compose file itself (the ${VAR} syntax above)

POSTGRES_PASSWORD=dev-password-local
REDIS_PASSWORD=redis-local-secret
DATABASE_URL=postgresql://myuser:dev-password-local@db/myapp_dev

# Note: Docker Compose reads .env for ${VAR} substitution in the YAML.
# For actual container env vars, use env_file: or environment: in the service.

# Run and check that env vars are injected correctly
docker compose up

# Verify in a running container
docker compose exec app printenv | grep DATABASE_URL

# Use a custom env file for variable substitution
docker compose --env-file .env.staging up

# Override a single variable for a one-off run
DATABASE_URL=postgresql://localhost/test docker compose up

# Create a Docker secret (Docker Swarm)
echo "postgresql://user:prod-password@db.internal/prod" |   docker secret create database_url -

echo "sk_live_your_real_stripe_key" |   docker secret create stripe_secret_key -

# List secrets (values are never shown)
docker secret ls

# docker-compose.yml with secrets (Docker Swarm mode)
version: '3.9'

services:
  app:
    image: myapp:latest
    secrets:
      - database_url
      - stripe_secret_key
    environment:
      - NODE_ENV=production
      - PORT=3000
      # Do NOT put sensitive values here in production

secrets:
  database_url:
    external: true    # Secret was created with 'docker secret create'
  stripe_secret_key:
    external: true

// Node.js app — read secrets from files (not process.env)
const fs = require('fs');
const path = require('path');

function readSecret(secretName) {
  try {
    // Docker mounts secrets at /run/secrets/<secret_name>
    return fs.readFileSync(
      path.join('/run/secrets', secretName),
      'utf8'
    ).trim();
  } catch (err) {
    // Fallback to process.env for local dev (where secrets aren't mounted)
    return process.env[secretName.toUpperCase().replace(/-/g, '_')];
  }
}

const DATABASE_URL = readSecret('database_url');
const STRIPE_SECRET = readSecret('stripe_secret_key');

// Now use DATABASE_URL and STRIPE_SECRET as normal strings