In 2011, Heroku published a methodology for building cloud-native applications that are portable, scalable, and maintainable. Twelve principles. Container technology didn't exist yet — but containers turned out to be the best vehicle for enforcing them.

1. What Is the Twelve-Factor App?

The Twelve-Factor App methodology was authored by Adam Wiggins and the Heroku team after observing hundreds of production applications. Its goal: a set of principles that, if followed, produce apps that can be deployed to any cloud, scaled horizontally without architectural changes, and maintained by any developer on the team.

The twelve factors span three concerns:

• Codebase hygiene — how you store and version your app
• Runtime behaviour — how the app starts, configures itself, and exits
• Operational posture — how it fits into the surrounding infrastructure

2. The 12 Factors, Container-Mapped

3. Build → Release → Run Pipeline (Factor V)

Factor V is the most structurally important for container workflows. The key rule: once an image is built, it must never be modified. Config is layered on at release time; the container runs exactly what was released.

# BUILD — produces immutable image
docker build -t myapp:v1.4.2 .

# RELEASE — image + runtime config = a versioned release
# (the image is never changed; env vars supply the config)
docker tag myapp:v1.4.2 registry.example.com/myapp:v1.4.2
docker push registry.example.com/myapp:v1.4.2

# RUN — instantiate the release as one or more containers
docker run -d \
  -e DATABASE_URL=postgres://prod-db:5432/app \
  -e REDIS_URL=redis://prod-cache:6379 \
  registry.example.com/myapp:v1.4.2

4. Factors Containers Enforce Naturally

These factors are almost automatic consequences of building and running containers correctly:

Factor III — Config via Environment Variables

Passing -e KEY=VALUE or using env: in Compose is the default way to configure containers. There's no temptation to edit a config file inside the container — the container filesystem is ephemeral. Environment variables are the canonical interface.

services:
  api:
    image: myapp:v1.4.2
    environment:
      DATABASE_URL: postgres://db:5432/app
      LOG_LEVEL: info
      SECRET_KEY: ${SECRET_KEY}   # from host env or .env file

Factor V — Build/Release/Run Separation

Docker's image model enforces this architecturally. You cannot modify a built image without rebuilding it. The tag is your release version. docker run is the run stage.

Factor VI — Stateless Processes

Containers have no persistent local storage by default. Anything written to the container filesystem vanishes on removal. This forces you to externalise state to backing services — databases, object stores — exactly as Factor VI requires.

Factor IX — Disposability

Containers are designed to be stopped, removed, and replaced within seconds. The container lifecycle maps directly: docker stop sends SIGTERM → app drains → exit 0. Fast startup and graceful shutdown are requirements, not niceties.

Factor X — Dev/Prod Parity

The same image runs on a laptop, in CI, in staging, and in production. The only difference is environment variables. This eliminates the "works on my machine" class of bugs entirely.

5. Factors You Must Consciously Apply

These factors don't fall out automatically — they require deliberate design choices.

Factor IV — Backing Services as Attached Resources

The principle: your database should be swappable between a local container and a managed RDS instance without any code change. Only the connection URL changes (via env var). This requires discipline:

# Correct: URL from env — swap prod/dev without code change
DATABASE_URL=postgres://localhost:5432/dev   # local
DATABASE_URL=postgres://rds.example.com/prod # production

# Wrong: hardcoded hostname or IP inside the application code
db = connect("localhost", 5432, "mydb")  # ❌ breaks outside dev

Factor VIII — Concurrency via the Process Model

Scaling out means running more container replicas, not making one container do more. This requires an orchestrator (Compose, Swarm, Kubernetes) and a stateless app (see Factor VI). Common mistakes: in-process job queues that only one replica can drain, session state held in memory, or websocket state not shared via Redis.

# Scale web and worker independently
docker compose up --scale web=4 --scale worker=2

Factor XI — Logs as Event Streams

The app must write to stdout/stderr — not to files, not to syslog, not to a database. Docker captures these streams and routes them to the configured log driver. Common mistake: a legacy app that writes to /var/log/app.log inside the container. The log driver never sees it, log rotation never runs inside the container, and the container's writable layer bloats over time.

# Correct: write to stdout — Docker log drivers handle the rest
console.log(JSON.stringify({ level: "info", msg: "Request received" }));

# Check what your container actually writes
docker logs mycontainer

# Route to a log aggregator via log driver
docker run --log-driver=fluentd --log-opt fluentd-address=localhost:24224 myapp

6. Anti-Patterns

7. Industry: Heroku, Cloud Run, and Fargate

Hands-On Task: Audit a Dockerfile & Compose Setup

# Dockerfile (to audit)
FROM node:20

WORKDIR /app
COPY . .
RUN npm install

# Hardcode the environment
ENV NODE_ENV=production
ENV DATABASE_HOST=prod-db.internal
ENV DATABASE_PASSWORD=supersecret123
ENV LOG_FILE=/var/log/app.log

RUN mkdir -p /var/log

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

# compose.yaml (to audit)
services:
  app:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - ./uploads:/app/uploads
    # No restart policy
    # No health check

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: supersecret123
    # Data stored only in container filesystem (no volume)

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: production
      DATABASE_URL: ${DATABASE_URL}      # from .env or shell
    restart: on-failure:5
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      retries: 3
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      retries: 5

volumes:
  pgdata:

FROM node:20-slim

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production    # install before copying app code (cache)

COPY . .

# No ENV for config — supplied at runtime
# No log directory — app writes to stdout

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

Interactive Quizzes

Key Takeaways

• Twelve-factor predates containers but describes exactly how container-native apps should behave
• Containers enforce naturally: config via env (III), build/release/run (V), statelessness (VI), disposability (IX), dev/prod parity (X)
• Conscious effort required for: backing services as URLs (IV), horizontal concurrency (VIII), logging to stdout (XI)
• Factor V is the foundation: build once, release with config, run anywhere — never mutate a running container
• Logs to stdout, not files — Docker log drivers and external aggregators need the stream to be there
• Admin tasks belong in one-off ephemeral containers (docker run --rm), not in the running service
• Heroku, Cloud Run, Fargate are built on twelve-factor assumptions — compliance is the price of admission to modern PaaS
• Auditing an existing app against the 12 factors is the fastest way to identify portability and scalability bottlenecks