Jamie-BitFlight Twelve Factor App
The Twelve-Factor App is a methodology for building software-as-a-service applications that are portable, deployable on modern cloud platforms, and scalable without significant architectural changes. Originally published in 2011 by Adam Wiggins (Heroku), the methodology was open-sourced in November 2024 and is now actively maintained at github.com/heroku/12factor with community-driven updates for Kubernetes, containers, and GitOps workflows.
SOURCE: https://12factor.net/blog/open-source-announcement (accessed 2026-02-26)
The Twelve Factors
| Factor | Principle |
|---|---|
| I. Codebase | One codebase tracked in revision control, many deploys |
| II. Dependencies | Explicitly declare and isolate dependencies |
| III. Config | Store config in the environment |
| IV. Backing services | Treat backing services as attached resources |
| V. Build, release, run | Strictly separate build and run stages |
| VI. Processes | Execute the app as one or more stateless processes |
| VII. Port binding | Export services via port binding |
| VIII. Concurrency | Scale out via the process model |
| IX. Disposability | Maximize robustness with fast startup and graceful shutdown |
| X. Dev/prod parity | Keep development, staging, and production as similar as possible |
| XI. Logs | Treat logs as event streams |
| XII. Admin processes | Run admin/management tasks as one-off processes |
Modern Extensions (Beyond 12-Factor)
Three additional factors are widely adopted in cloud-native practice, established by Kevin Hoffman's Beyond the Twelve-Factor App (O'Reilly, 2016) and formalized in the 15-factor methodology:
| Factor | Principle |
|---|---|
| XIII. API-First | Design and publish the service API contract before implementing the backing logic |
| XIV. Telemetry | Treat observability (metrics, traces, structured logs) as a first-class operational requirement |
| XV. Authentication and Authorization | Elevate identity, authn, and authz to first-class concerns in service design |
SOURCE: https://www.oreilly.com/library/view/beyond-the-twelve-factor/9781492042631/ (accessed 2026-02-26)
Reference Categories
Methodology Overview
Background, goals, target audience, and design philosophy.
Codebase and Dependencies (Factors I and II)
Version control discipline and explicit dependency management.
Configuration and Backing Services (Factors III and IV)
Environment-based config and treating backing services as swappable attached resources.
Build, Release, Run (Factor V)
Strict separation of the three stages that transform a codebase into a running deploy.
Processes and Port Binding (Factors VI and VII)
Stateless share-nothing process execution and self-contained service export via port binding.
Concurrency and Disposability (Factors VIII and IX)
Scaling via the process model and building robust disposable processes.
Dev/Prod Parity and Logs (Factors X and XI)
Minimizing environment gaps and treating logs as event streams.
Admin Processes (Factor XII)
Running one-off administrative and maintenance tasks as processes in the same environment as the app.
Modern Evolution
Open-source governance, narrow-conduit concept, 15-factor extensions, Reactive Principles, and monolith modernization patterns.
Quick Compliance Checklist
Use this to audit an application against the methodology:
- Single codebase in VCS; shared code extracted to libraries (I)
- All dependencies declared in manifest; isolation tool in use (II)
- All deploy-varying config in env vars; no config in code (III)
- Backing services accessed via URL/credentials from config; swappable without code changes (IV)
- Build, release, run stages strictly separated; releases immutable with unique IDs (V)
- Processes stateless and share-nothing; no sticky sessions; session state in external store (VI)
- App self-contained; webserver library bundled; service exported via port binding (VII)
- Scale via adding processes, not growing single process; no daemonizing or PID files (VIII)
- Fast startup; graceful SIGTERM handling; robust against sudden death (IX)
- Dev and prod use same backing service types; time/personnel/tools gaps minimized (X)
- All log output to stdout; no log file management in app code (XI)
- Admin tasks run as one-off processes against same release and config as regular processes (XII)
- Service API contract defined and documented before implementation (XIII)
- Metrics, distributed traces, and structured logs emitted; observability platform configured (XIV)
- Authentication and authorization handled as first-class concerns; no ad-hoc security (XV)