jamie-bitflight/twelve-factor-app

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.

• ./references/methodology-overview/index.md

Codebase and Dependencies (Factors I and II)

Version control discipline and explicit dependency management.

• ./references/codebase-and-dependencies/index.md

Configuration and Backing Services (Factors III and IV)

Environment-based config and treating backing services as swappable attached resources.

• ./references/configuration-and-backing-services/index.md

Build, Release, Run (Factor V)

Strict separation of the three stages that transform a codebase into a running deploy.

• ./references/build-release-run/index.md

Processes and Port Binding (Factors VI and VII)

Stateless share-nothing process execution and self-contained service export via port binding.

• ./references/processes-and-port-binding/index.md

Concurrency and Disposability (Factors VIII and IX)

Scaling via the process model and building robust disposable processes.

• ./references/concurrency-and-disposability/index.md

Dev/Prod Parity and Logs (Factors X and XI)

Minimizing environment gaps and treating logs as event streams.

• ./references/dev-prod-parity-and-logs/index.md

Admin Processes (Factor XII)

Running one-off administrative and maintenance tasks as processes in the same environment as the app.

• ./references/admin-processes/index.md

Modern Evolution

Open-source governance, narrow-conduit concept, 15-factor extensions, Reactive Principles, and monolith modernization patterns.

• ./references/modern-evolution/index.md

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)