Twelve-Factor App
Methodology for building scalable, maintainable cloud-native apps
The Twelve-Factor App methodology, published by Heroku engineers in 2012, defines twelve principles for building software-as-a-service applications that are portable, scalable, and maintainable. The factors address the full software delivery lifecycle — from codebase management through configuration, dependency isolation, process model, and disposability. A twelve-factor app can be deployed to any cloud without modification, scales horizontally by adding process instances, and has no divergence between development and production environments. These principles have become the baseline expectation for cloud-native architecture and underpin Kubernetes pod design, container image best practices, and GitOps workflows.
Key Points
- Factor I (Codebase): one repo per app tracked in version control; multiple deploys (dev, staging, prod) from the same codebase — never one repo per environment.
- Factor III (Config): store all config that varies between deployments in environment variables — never hardcode credentials, service URLs, or feature flags in code or config files committed to source control.
- Factor V (Build/Release/Run): strictly separate build (compile + bundle), release (build + config = immutable artifact), and run (execute release) — enables atomic rollback by deploying a previous release.
- Factor VI (Processes): execute as one or more stateless processes; share-nothing between instances; external state (sessions, queues, files) lives in a backing service, not in process memory.
- Factor VII (Port Binding): export services via port binding (an HTTP server embedded in the app, not deployed into an app server) — the app is self-contained; routing is the platform's job.
- Factor IX (Disposability): fast startup (seconds, not minutes) and graceful shutdown — enables elastic scaling, deployment without downtime, and crash-safe operation with automatic restart.
- Factor X (Dev/Prod Parity): minimize time, personnel, and tool gaps between development and production environments — Docker Compose locally mirrors Kubernetes in prod to prevent "works on my machine" failures.
- Factor XI (Logs): treat logs as event streams to stdout/stderr — never manage log files in the app; let the execution environment (Kubernetes, Heroku) route log streams to Splunk, Datadog, or CloudWatch.
| Factor | Name | Principle | Anti-Pattern to Avoid |
|---|---|---|---|
| I | Codebase | One codebase tracked in VCS, many deploys | Separate repos per environment; copy-paste codebases |
| II | Dependencies | Explicitly declare and isolate dependencies | Relying on system-wide installed packages (no package.json/requirements.txt) |
| III | Config | Store config in environment variables | Config files committed to git; hardcoded credentials |
| IV | Backing Services | Treat backing services as attached resources | Distinguishing local vs. remote DB in code; hardcoded service URLs |
| V | Build/Release/Run | Strictly separate build and run stages | SSH-ing into production to make changes; mutable deployments |
| VI | Processes | Execute as stateless, share-nothing processes | Sticky sessions; in-memory session state; local file system state |
| VII | Port Binding | Export services via port binding | Deploying to external app servers (Tomcat war files); managed app containers |
| VIII | Concurrency | Scale out via the process model | Threads as primary concurrency unit; scaling by making one process bigger |
| IX | Disposability | Fast startup, graceful shutdown | Long startup time; not handling SIGTERM gracefully; in-flight request dropping |
| X | Dev/Prod Parity | Keep dev, staging, prod as similar as possible | SQLite in dev, PostgreSQL in prod; different OS between local and prod |
| XI | Logs | Treat logs as event streams | Writing log files to disk; log rotation inside the app; parsing structured logs from files |
| XII | Admin Processes | Run admin tasks as one-off processes | Running migrations inside the app startup; SSH ad-hoc scripts |
Real-World Example
Heroku's entire platform is an implementation of the Twelve-Factor methodology — the dyno model (Factor VI, VIII), config vars (Factor III), add-ons as attached resources (Factor IV), and the release system (Factor V) directly implement these principles. The methodology's influence is visible in every Kubernetes deployment: container images are immutable releases, environment variables carry config, and health checks enforce disposability.