The Twelve-Factor App

The twelve factors in brief

1. Codebase: one codebase in version control, many deploys.
2. Dependencies: declare and isolate them explicitly.
3. Config: store it in the environment, not in code.
4. Backing services: treat databases, queues and caches as attached resources.
5. Build, release, run: keep these stages strictly separate.
6. Processes: run the app as one or more stateless processes.
7. Port binding: export services by binding to a port.
8. Concurrency: scale out through the process model.
9. Disposability: start fast and shut down gracefully.
10. Dev/prod parity: keep development, staging and production as similar as possible.
11. Logs: treat them as event streams written to standard output.
12. Admin processes: run one-off tasks as one-off processes.

Each factor has its own short page with the reasoning behind it.

Why it is still the reference

The site says it was last updated in 2017, and the methodology has since been open sourced for community revision. Even so, almost every convention in containers, Kubernetes and platform services traces back to one of these ideas. Environment variables for secrets, twelve-factor style logging to stdout, and stateless containers you can kill at any time are all here, explained from first principles.

Where to apply it first

Configuration and statelessness. Those two cause most of the pain when an app that runs on a laptop refuses to run anywhere else. Hard coded URLs, config files baked into the image, and user sessions or uploads stored on local disk all break as soon as you run two copies. Both are cheap to fix early and expensive to retrofit.

Where it shows its age

It was written before containers and orchestration became standard, so it says little about health checks, service meshes, secrets managers or observability beyond logs. Some teams deliberately bend factor three and use a secrets store instead of plain environment variables. Read it as a set of reasons, not rules to follow blindly.

Common questions

Is it outdated? The content was last updated in 2017, but the source has since been opened up on GitHub (about 2.8k stars as of September 2026) for community revision. The core ideas remain standard practice.

How long does it take? About an hour to read all twelve pages carefully.

Do I need it if I use Kubernetes? Yes. Kubernetes assumes apps behave like twelve-factor apps; knowing why makes deployments far less surprising.

Best for: backend developers whose deployments are unreliable, and anyone containerising an application for the first time.