Build apps that
scale, deploy & survive

Codebase

The problem it solves

Imagine a team keeps two copies of their code in separate folders — app-prod for the live site and app-test for experiments — and edits each one by hand. Over time the two copies stop matching: a bug fixed in one is forgotten in the other, and soon nobody can say which copy is the "real," correct version. That confusion is exactly what this factor prevents.

The opposite mistake is just as bad: cramming several unrelated apps into one giant codebase, so changes to one app accidentally affect the others and no team clearly "owns" any part of it. The rule is simple: one app, one codebase — no copies, no crowding.

The rule

• One repo per app. Tracked in Git (or similar).
• Many deploys from it. Your laptop, staging, and production all run the same codebase at possibly different commits.
• Shared code between apps belongs in a library/package, not copy-paste.

In practice

This factor isn't Python code — it's how you use version control. You create the repository once, then every environment gets its own deploy from that same repo:

# Create the single codebase (done once)
$ git init
$ git add . && git commit -m "first version"
$ git remote add origin git@github.com:me/my-app.git
$ git push -u origin main

# Each environment is a DEPLOY of that same repo — never a copy.
# Production runs a specific, known commit (here a release tag):
$ git checkout v1.4.0   &&  deploy_to prod

# Staging can run the latest main while you test:
$ git checkout main     &&  deploy_to staging

# "Which exact code is live?" always has an answer — the commit hash:
$ git rev-parse HEAD     # e.g. 9f3c1a7… → that's what prod is running

Dependencies

The problem it solves

"It works on my machine!" Usually this means your machine happens to have a tool or library that the server doesn't. A 12-factor app removes that guesswork: dependencies are declared (written down) and isolated (your app can't accidentally use a system-wide version).

In Python

# No manifest. You just hope
# requests is installed globally.
import requests
# Works on your laptop, crashes
# on the server. 💥

# requirements.txt — pinned versions
flask==3.0.3
requests==2.32.3
gunicorn==22.0.0

# isolated environment
$ python -m venv .venv
$ source .venv/bin/activate
$ pip install -r requirements.txt

Config

The problem it solves

If your database password is hard-coded in app.py, then (a) it ends up in Git history for the world to see, and (b) you need a different copy of the code for every environment. Config is the stuff that differs between deploys; code is what stays the same.

The litmus test

In Python

DB_URL = "postgres://admin:s3cret@" \
         "prod-db.internal:5432/app"
DEBUG  = True
# Secret in Git. One file per env. 😱

import os

DB_URL = os.environ["DATABASE_URL"]
DEBUG  = os.environ.get("DEBUG", "false") == "true"
# Same code everywhere; values
# injected per environment.

Locally, you keep values in a .env file (and add it to .gitignore!). A library like python-dotenv loads them:

# .env  (NEVER commit this)
DATABASE_URL=postgres://localhost:5432/app_dev
DEBUG=true

# app.py
from dotenv import load_dotenv
load_dotenv()  # reads .env into os.environ for local dev

Backing services

The problem it solves

A "backing service" is any add-on your app consumes over the network: PostgreSQL, Redis, RabbitMQ, an SMTP server, an S3 bucket, a third-party API. A 12-factor app makes no distinction between a service running on your own laptop and one run by a third party. Both are just resources located by a URL in config.

In Python

The app reads each service's address from config (Factor 3) and connects to it. The code never hard-codes where the service lives:

import os
import psycopg          # PostgreSQL driver
import redis

# The connection URL comes from the environment, not the code.
db    = psycopg.connect(os.environ["DATABASE_URL"])
cache = redis.from_url(os.environ["REDIS_URL"])

Now switching services is purely a config change — no code edits, no redeploy of the code itself. You just point the same app at a different URL:

# Local development — services running on your own machine
DATABASE_URL=postgres://localhost:5432/app_dev
REDIS_URL=redis://localhost:6379

# Production — same code, now pointed at managed cloud services
DATABASE_URL=postgres://user:pass@db.cloud-provider.com:5432/app
REDIS_URL=rediss://user:pass@cache.cloud-provider.com:6380

Build, release, run

The three stages

What the three stages look like

With Docker, the three stages map to commands you (or your CI pipeline) run in order:

# ── BUILD ── turn source code into one fixed artifact (an image),
#            tagged with the exact commit so it's traceable.
$ docker build -t myapp:9f3c1a7 .

# ── RELEASE ── combine that artifact with this environment's config.
#              The build never changes; only the config is attached.
$ docker run --env-file prod.env myapp:9f3c1a7   # release v42

# ── RUN ── the platform just launches the chosen release. Nothing
#          is built or edited here — it only starts the processes.

# ── ROLLBACK ── a bad deploy? Don't patch it — just RUN an older,
#               already-built release again. Instant and safe.
$ docker run --env-file prod.env myapp:e1b88d2   # previous release

Processes

The problem it solves

If a process stores your shopping cart in its own memory, then your next request — which might hit a different copy of the app — sees an empty cart. And if that process restarts, the data is gone. Statelessness means any process can handle any request.

A simple example: a visitor counter

Say your app counts page visits. The naive version keeps the count in a normal variable — in the process's memory:

visits = 0   # lives in THIS copy's memory only

def home():
    global visits
    visits += 1
    return f"You are visitor #{visits}"

On your laptop, with one copy running, this looks fine. But in production you run several copies behind a load balancer (Factor 8). Now each copy has its own separate visits variable, so users get inconsistent numbers — and a restart resets that copy to zero:

The fix is to keep the count in a shared backing service — here Redis. Every copy reads and updates the same number, so they all agree and a restart loses nothing:

import os, redis
store = redis.from_url(os.environ["REDIS_URL"])

def home():
    # INCR lives in Redis, shared by ALL copies.
    visits = store.incr("visits")
    return f"You are visitor #{visits}"

In Python

sessions = {}  # in-process dict

def login(user):
    # Lost on restart; invisible to
    # other processes. 💥
    sessions[user.id] = make_token()

import redis
store = redis.from_url(os.environ["REDIS_URL"])

def login(user):
    # Shared, survives restarts,
    # visible to all processes.
    store.set(user.id, make_token())

Port binding

The problem it solves

The old model required you to install your app inside a heavyweight web server (e.g. drop PHP files into Apache). A 12-factor app flips this: the app itself binds to a port and speaks HTTP. The platform routes public traffic to that port.

In Python

import os
from flask import Flask

app = Flask(__name__)   # this IS the web server — no Apache needed

if __name__ == "__main__":
    # Read the port from config; if it's not set, fall back to 8000.
    port = int(os.environ.get("PORT", 8000))

    # Start listening. host="0.0.0.0" means "accept visitors from
    # anywhere", not just this one machine.
    app.run(host="0.0.0.0", port=port)

For real traffic, the tiny built-in server isn't strong enough, so you run the same app behind a production server called Gunicorn. Notice it's still the exact same idea — bind the app to a port:

# "app:app" = the file app.py, and the variable named app inside it.
# $PORT is the port number the platform tells us to use.
$ gunicorn app:app --bind 0.0.0.0:$PORT

Concurrency

The process formation

Different kinds of work become different process types. A common split: web processes handle HTTP requests, worker processes handle background jobs from a queue. You scale each type independently based on its load.

In practice

You declare your process types once — here in a Procfile, a simple list of "name: command to run":

# Procfile — defines the kinds of processes your app can run
web:    gunicorn app:app --bind 0.0.0.0:$PORT   # handles HTTP requests
worker: python worker.py                        # handles background jobs

Then you scale each type just by choosing how many copies to run — no code change at all:

# Normal load
$ scale web=2 worker=1

# Big sale today → add more copies of each type independently
$ scale web=5 worker=3

# (On Kubernetes the same idea is "replicas":)
$ kubectl scale deployment web --replicas=5

Disposability

Two qualities

• Fast startup: a process is ready in seconds, so you can scale up quickly and recover from crashes fast. Just be sure it's truly ready before it accepts traffic — database and network connections established — so the first users don't hit a half-booted app.
• Graceful shutdown: on a stop signal (SIGTERM), the process stops taking new work, finishes what it's doing, and exits cleanly. Background jobs return unfinished work to the queue.

In Python

When a platform wants to stop your app (to redeploy, scale down, or move it), it doesn't kill it instantly — it first sends a polite "please wrap up now" message called SIGTERM. Your job is to listen for that message and shut down cleanly instead of dropping work mid-way:

import signal, sys

# This function runs when the platform asks the app to stop.
def shutdown(signum, frame):
    print("Stop requested — finishing current work, then exiting")

    # 1. Stop taking NEW requests, but let the ones already
    #    in progress finish (your own helper function).
    drain_in_flight_requests()

    # 2. Tidy up: close database connections, etc.
    close_db_connections()

    # 3. Exit calmly. Code 0 means "stopped on purpose, no error".
    sys.exit(0)

# Tell Python: when SIGTERM arrives, run shutdown() above.
signal.signal(signal.SIGTERM, shutdown)

drain_in_flight_requests() and close_db_connections() are placeholders for your own cleanup steps — the key idea is the pattern: catch the stop signal, finish gracefully, then exit.

Dev/prod parity

The three gaps to close

In practice

A docker-compose.yml file lets you run the real database and cache on your laptop with one command — the same versions you use in production, so there are no surprises:

# docker-compose.yml — your local stack mirrors production
services:
  web:
    build: .
    environment:
      DATABASE_URL: postgres://app@db:5432/app
      REDIS_URL: redis://cache:6379
  db:
    image: postgres:16        # SAME version as prod — not SQLite
  cache:
    image: redis:7            # SAME version as prod

# Start the whole production-like stack locally:
$ docker compose up

Logs

The problem it solves

When apps write and rotate their own log files, you get a mess: logs scattered across machines, custom rotation code, and no easy way to search across many processes. It's even worse with containers — a log file written inside a container is destroyed when that container is thrown away (which happens constantly), taking your evidence with it. The 12-factor approach: the app does the simplest possible thing — write to stdout — and leaves the rest to the platform.

In Python

# App decides WHERE logs are stored
# and is responsible for managing
# that file forever.
logging.basicConfig(
  filename="/var/log/app.log")

# Problems: a separate file on every
# machine, you must delete old logs
# yourself, and searching across all
# copies of the app is painful.

import logging, sys

# App only prints events to the screen
# (stdout). It does NOT manage files.
logging.basicConfig(
  stream=sys.stdout,
  level=logging.INFO)

# The platform captures this output and
# handles storing, searching & cleanup.

Modern tip: structured logs

Instead of printing plain sentences, print each log as a small JSON object on its own line (this is called a "structured log"). Machines can read JSON easily, so search tools can instantly filter by things like the user or the error type:

import json, sys

def log(**fields):
    # Print one JSON object per line to stdout...
    print(json.dumps(fields), file=sys.stdout, flush=True)
    # flush=True = "unbuffered": send it out NOW, don't wait to
    # collect a batch first. So events appear the instant they happen.

log(event="login", user_id=42, ok=True)
log(event="payment_failed", order_id=99, reason="card_declined")

Each call prints one line, e.g. {"event": "login", "user_id": 42, "ok": true}.

Admin processes

The problem it solves

Admin work (migrating a schema, running a cleanup script) often gets done with ad-hoc scripts on a random machine, against a different version of the code. That causes drift and "it ran fine in the script but broke the app" surprises.

In Python

# Run the migration using the SAME release + config as the app:
$ python manage.py migrate            # Django
$ flask db upgrade                     # Flask-Migrate

# A one-off interactive shell against the live app's code/config:
$ python manage.py shell

# On a platform, run it as a one-off process in the prod environment:
$ heroku run python manage.py migrate
$ kubectl run migrate --image=myapp:v42 -- python manage.py migrate