The Twelve-Factor App and Environment Config

Intermediate · 30 min

Why config lives in environment variables, not code, and the twelve-factor discipline that makes a service portable across dev, staging, and prod.

Before thisWeb Frameworks and the Request-Response Cycle

KodeKloud · 30 min

The Twelve-Factor App and Environment Config

The player loads from youtube-nocookie.com when you press play. Nothing reaches YouTube before that.

Taught by KodeKloudReport a problem with this video
Not started
Set this lesson's status

What you'll learn

  • Config is anything that varies between dev, staging, and prod — database URLs, API keys, feature flags — and the twelve-factor rule is to pull all of it out of code and into environment variables.
  • Strict separation of config from code means the exact same build artifact can run in every environment unchanged; only what's injected at startup differs, which is what actually makes a deploy portable.
  • Dev/prod parity means keeping the backing services (database type, cache, queue) as close to identical as possible across environments, so "works on my machine" failures show up in dev instead of at 2am in prod.
  • A stateless process treats anything that must survive a restart — session data, uploaded files, in-progress job state — as something to be stored in a backing service, not in the process's own memory or local disk.
  • Backing services (a database, a cache, a message queue) should be attached as swappable resources reachable via config, not hardcoded, so swapping a local Postgres for a managed one takes a config change, not a code change.

The problem this discipline is solving

Every backend service eventually needs to run in more than one place: your laptop while you’re building it, a staging environment before a release, production once it’s live, and probably a teammate’s laptop too. Each of those places needs slightly different values — a different database to talk to, a different API key, different log verbosity — but you want the exact same code running in all of them. The moment code and configuration get tangled together, you lose that: a database hostname hardcoded in a file means either maintaining different versions of that file per environment, or manually editing it before every deploy, both of which are exactly the kind of manual step that eventually gets forgotten and breaks something in prod that worked fine in staging.

The twelve-factor app methodology, written by engineers at Heroku in 2011, is a set of practices for avoiding that class of problem. Not all twelve factors carry equal weight for a typical application developer — some (like how logs get collected centrally) are more an ops concern. The ones that actually change how you write a service day to day are config, statelessness, dev/prod parity, and backing services, and those are what this lesson focuses on.

Config: the one factor that touches almost every app

“Config” here means anything that legitimately differs between deployments of the exact same code: database connection strings, third- party API keys, which feature flags are on, how verbose logging should be. The twelve-factor rule is blunt about where that belongs: in environment variables, read by the process at startup, never hardcoded and never committed to the repository as a per-environment file.

DATABASE_URL=postgres://user:pass@db.prod.internal:5432/app
STRIPE_API_KEY=sk_live_xxxxxxxxxxxx
LOG_LEVEL=info
import os

database_url = os.environ["DATABASE_URL"]

The reasoning is stricter than “it’s convenient”: config stored any other way tends to leak. A config.py with a real API key in it that gets committed once, even accidentally, lives forever in git history. An environment variable supplied by the hosting platform at deploy time never touches the repository at all. The practical test the original manifesto proposes is a good one: could you make your codebase open source right now, with everything in it, without exposing a credential? If a config file with real secrets in it would stop you, config and code aren’t separated yet.

Why separation makes a deploy actually portable

The payoff of pulling config out of code isn’t abstract. It means you can build your application once — one artifact, one container image, one compiled binary — and deploy that exact same artifact to dev, staging, and production, with only the environment variables around it changing. Nobody is rebuilding the app per environment, which also means nobody is accidentally testing a slightly different build in staging than the one that ships to prod. The code is identical everywhere; only what’s injected at runtime differs.

Stateless processes: nothing survives in memory that needs to

A process following this discipline treats its own memory and local disk as disposable. If a request handler stores a user’s session data in a local in-memory dictionary, that session is gone the instant the process restarts — and worse, it’s invisible to every other instance of your app running behind a load balancer, so the same user hitting a different instance on their next request looks logged out. The fix is to push anything that needs to outlive a single request into a backing service built for it: session data into a shared cache like Redis, uploaded files into object storage, long-running job state into a database or queue — not into the process’s own memory.

This is also what makes horizontal scaling — just running more copies of the same process — actually work. If every process is stateless, a load balancer can send a request to any of them interchangeably. If state is scattered across individual process memory, scaling out just means some requests silently hit the wrong copy.

Backing services: attached, not embedded

A backing service is anything your app talks to over the network to do its job: a database, a cache, a message queue, an email-sending API. The twelve-factor discipline treats every one of these as an attached resource, reachable only through config — a URL and credentials pulled from the environment — never assumed to be a specific, hardcoded instance. Done properly, swapping a local Postgres instance for a managed cloud database is a one-line config change, not a code change, because the application code never cared which specific instance it was talking to in the first place.

Dev/prod parity: close the gaps that actually bite you

Parity doesn’t mean your laptop needs production’s exact hardware — it means keeping the things that cause behavioral differences close together: the same database engine and roughly the same version in dev as in prod, rather than SQLite locally and Postgres in production; backing services that behave the same way under the same operations. A backend- specific bug caused by a database engine difference is exactly the kind of thing parity is meant to catch in development, where it’s cheap to fix, instead of in production, where it isn’t.

This lesson has been about the discipline inside your own application — environment variables, statelessness, parity, treating backing services as attached resources. At real organizational scale, actually storing, rotating, and distributing those secrets across many services and teams becomes its own infrastructure problem, with dedicated tooling like a secrets vault. That’s a different, larger problem built on top of the same principle, and it’s covered in secrets and config management.

Check yourself

  1. 01Why does the twelve-factor methodology insist config lives in environment variables instead of, say, a settings.py or appsettings.json file committed to the repo?

    A file in the repo is still code — it travels with every deploy, gets the same value in every environment unless you maintain multiple copies, and risks committing real secrets to version control. Environment variables are supplied by the deploy environment itself, so the identical build artifact gets different config depending on where it's actually running.

  2. 02What does "strict separation of config from code" actually buy you in practice?

    The ability to build one artifact once and deploy that exact same artifact to dev, staging, and prod — only the environment variables injected at startup change. Without that separation you end up rebuilding, or worse, manually editing, the app per environment, which is exactly how a staging-only bug ends up untested until it's in prod.

  3. 03Why does a stateless process matter for scaling a service horizontally?

    If a process keeps session data or job state only in its own memory, a load balancer sending the next request to a different process (or the same process after a restart) loses that state entirely. Keeping that state in a backing service like a shared cache or database means any process can handle any request, which is what lets you add or remove processes freely.

  4. 04What's the practical difference between this lesson's "config in your own app" framing and secrets-and-config-management at the system-design level?

    This lesson is about the discipline of how you structure config and secrets within a single service you're writing — env vars, no config in code, parity across environments. The system-design-level lesson is about the vault infrastructure an organization runs at scale to actually store, rotate, and distribute those secrets across many services and teams — a different, larger problem built on top of the same underlying principle.

  5. 05Why does dev/prod parity matter even though a developer's laptop will never be identical to a production cluster?

    Parity isn't about making the environments physically identical — it's about keeping the things that actually cause behavioral differences (database engine and version, cache behavior, how long a deploy takes) as close as practical, so the backend-specific bugs that show up from those differences surface during development instead of only in production.

Go deeper

Notes

Private to you

Esc
↑↓ navigate↵ open? shortcuts

Keyboard shortcuts

Press Esc to close

Anywhere

⌘K
Search and commands
/
Search
?
This sheet
Esc
Close

Reading a lesson

J
Next lesson
K
Previous lesson
B
Bookmark