What Is the Twelve-Factor App Methodology?

Quick answer

• The Twelve-Factor App is a 12-point methodology for building software that runs cleanly in the cloud.
• Its principles cover codebase, dependencies, config, backing services, processes, and more.
• Two factors matter most day-to-day: config in the environment, and stateless, disposable processes.

What is the Twelve-Factor App?

The Twelve-Factor App is a methodology, first published around 2011 by engineers at Heroku, describing twelve principles for building software-as-a-service applications that are portable, scalable, and easy to operate in the cloud. It became a de facto standard for “cloud-native” design, and its ideas still shape how modern apps are structured and deployed.

The twelve factors

1. Codebase — one codebase per app, tracked in version control, with many deploys.
2. Dependencies — declare and isolate dependencies; never rely on implicit system packages.
3. Config — store config (including secrets) in the environment, not the code.
4. Backing services — treat databases and queues as attached resources, swappable by config.
5. Build, release, run — strictly separate the build, release, and run stages.
6. Processes — run the app as stateless processes that share nothing.
7. Port binding — the app self-contains its service and binds to a port.
8. Concurrency — scale horizontally via the process model.
9. Disposability — fast startup and graceful shutdown.
10. Dev/prod parity — keep environments as similar as possible.
11. Logs — treat logs as an event stream, not files to manage.
12. Admin processes — run one-off admin tasks as part of the same codebase.

Why it matters

The factors are a checklist against the failure modes that make software hard to run at scale: config baked into code, state hidden in the filesystem, processes that can’t be restarted safely. Apps that follow them are portable between environments, horizontally scalable, and predictable under the kind of automation modern platforms assume.

Which factors matter most now

For most teams, factors 3 (config) and 6 (stateless processes) cause the most pain. Config in the environment is the root of secrets management, and statelessness is what lets you scale, restart, and deploy without losing data. Get those two right and you’ve absorbed the heart of the methodology.

Where this bites vibecoders

AI assistants produce apps that violate the factors by default: config hardcoded, state written to local disk, logs scattered in files, environments that drifted. The value of the list is as a review checklist — after generation, walk the twelve and fix the violations that will bite first (config and state). It’s an old standard, but it’s never been more useful as a rubric for judging generated code.

Where AI coding assistants get this wrong

• Hardcoding config and secrets instead of reading the environment.
• Writing files to the local filesystem and assuming they persist.
• Emitting unmanaged log files instead of structured stdout.
• Ignoring graceful shutdown, so deploys drop in-flight work.

Checklist

• Read config and secrets from the environment.
• Keep processes stateless; move state to backing services.
• Declare and isolate dependencies.
• Log to stdout as a structured event stream.
• Support fast startup and graceful shutdown.

FAQ

Is the Twelve-Factor App still relevant?

Yes. Some details (like the original stance on logging and builds) have evolved, but the core principles — config in the environment, stateless processes, dev/prod parity — remain the foundation of cloud-native design and are assumed by modern platforms.

Does twelve-factor mean microservices?

No. The factors describe how to build a process, not how many services to have. A monolith can be twelve-factor, and many microservices aren’t. The methodology is about portability and operability, not service count. See Monolith vs Microservices.

What is a backing service?

A backing service is any external resource the app consumes — a database, a queue, a cache, an email service. Twelve-factor treats them as attached resources, referenced by config, so you can swap a local database for a managed one without code changes.

Related topics

• How to Manage Secrets and Environment Variables Properly
• What Is Serverless Computing?
• What Is a Feature Flag?

Sources

• The Twelve-Factor App