Twelve-Factor App
Twelve-factor is a methodology for deployable services: configuration from environment, stateless processes, logs to streams, and disposability — the contract cloud platforms automate around.
Definition
The twelve-factor methodology defines service properties that make applications portable and automatable on cloud infrastructure: one codebase many deploys, dependencies declared, configuration injected via environment, backing services attached by URL, strict build-release-run stages, stateless processes, port binding, concurrent scale via process types, fast startup and graceful shutdown, development-production parity, logs as event streams, and admin tasks as one-off processes.
Context and scope
The baseline contract for PaaS and Kubernetes-era deployments. Individual factors age into defaults, but violations — config in files, logs to disk, stateful processes — still break platform automation.
Common misconceptions
- It is outdated container-era advice — containers and orchestrators automate exactly these properties; the factors are the API they expect
- Configuration via environment covers secrets — environment variables leak into crash dumps, child processes, and ps output; secret managers exist for that reason
- Statelessness means no data at all — it means no state required for correctness of a request: caches and local scratch are fine, databases of record are not
Anti-patterns
- Baking environment-specific configuration into images and multiplying image variants per environment
- Writing logs to local files inside containers and losing them at pod eviction
- Keeping session state in process memory and breaking users on every rolling deploy
Related concepts
Authoritative source
What it is
Cloud platforms reward a specific contract: processes that start fast, read config from environment, keep no required state, and emit logs as stdout. Twelve-factor names that contract, enabling uniform automation across teams and languages.
How it works
Each factor removes a coupling: config-in-environment removes environment-specific builds; stateless processes remove session pinning; log streams remove disk management; disposability removes startup and shutdown ceremony. The sum is a service the platform can start, stop, move, and scale without the application noticing.
When to apply
Any service destined for container orchestrators or PaaS, where automation assumes the contract. Legacy systems adopt the factors incrementally — moving configuration and logs first, statelessness last — rather than as a single rewrite.
Pitfalls
Environment-only config struggles with large and structured values — externalized config services extend the factor rather than violate it. The factors say nothing about resilience, observability, or data — they are the deployment contract, not the whole architecture. Literal adherence without judgment recreates problems the factors never claimed to solve.