Twelve-Factor App Methodology Cheat Sheet

Updated 2026-03-18

The Twelve-Factor App is a methodology for building software-as-a-service applications created by Heroku co-founder Adam Wiggins in 2011. It codifies best practices for building cloud-native apps that are portable, resilient, and scalable across modern cloud infrastructure. The methodology emphasizes declarative configuration, stateless processes, and strict separation of concerns across twelve core principles. Originally designed for the PaaS era, these factors remain foundational to microservices, containerized applications, and cloud-native development in 2026—though modern extensions (15-factor, 16-factor) address AI workloads, observability, and API-first design.

What This Cheat Sheet Covers

This topic spans 17 focused tables and 124 indexed concepts. Below is a complete table-by-table outline of this topic, spanning foundational concepts through advanced details.

Table 1: The Twelve Core FactorsTable 2: Codebase & Version Control PatternsTable 3: Dependency Management TechniquesTable 4: Configuration & Environment VariablesTable 5: Backing Services & Attached ResourcesTable 6: Build, Release, Run StagesTable 7: Stateless Processes & Shared StateTable 8: Port Binding & Self-Contained ServicesTable 9: Concurrency & Process ModelTable 10: Disposability & RobustnessTable 11: Dev/Prod Parity & ConsistencyTable 12: Logging & ObservabilityTable 13: Admin Processes & One-Off TasksTable 14: Anti-Patterns & Common ViolationsTable 15: Cloud-Native & Container ConsiderationsTable 16: Modern Tools & TechnologiesTable 17: Beyond Twelve-Factor (Modern Extensions)

Table 1: The Twelve Core Factors

Factor	Example	Description
I. Codebase	`git clone repo && deploy to dev, staging, prod`	One codebase tracked in version control (Git, SVN), with many deploys—same source code runs across development, staging, and production environments with different configurations.
II. Dependencies	`package.json`, `requirements.txt`, `Gemfile`, `pom.xml`	• Explicitly declare and isolate all dependencies via a dependency manifest • never rely on system-wide packages • use dependency isolation tools (`virtualenv`, `bundler`, `npm install`).
III. Config	`DATABASE_URL=postgres://user:pass@host/db`	• Store config in environment variables (env vars)—credentials, resource locators, per-deploy settings—never hardcode in source • strict separation of config from code.
IV. Backing Services	`DATABASE_URL`, `REDIS_URL`, `S3_BUCKET`	• Treat backing services as attached resources—databases, queues, caches, SMTP, APIs accessed via URL/credentials in config • swappable without code changes.
V. Build, Release, Run	Build:`npm run build` → Release:`v123+config` → Run:`node app.js`	• Strict separation of three stages: Build (convert code to executable), Release (combine build + config), Run (execute app in environment) • no code changes at runtime.
VI. Processes	Stateless web workers; state in Redis/DB, not memory	• Execute app as stateless, share-nothing processes • any data that must persist goes to a stateful backing service (DB, cache) • enables horizontal scaling.

Table 1: The Twelve Core Factors

Factor	Example	Description
I. Codebase	`git clone repo && deploy to dev, staging, prod`	One codebase tracked in version control (Git, SVN), with many deploys—same source code runs across development, staging, and production environments with different configurations.
II. Dependencies	`package.json`, `requirements.txt`, `Gemfile`, `pom.xml`	• Explicitly declare and isolate all dependencies via a dependency manifest • never rely on system-wide packages • use dependency isolation tools (`virtualenv`, `bundler`, `npm install`).
III. Config	`DATABASE_URL=postgres://user:pass@host/db`	• Store config in environment variables (env vars)—credentials, resource locators, per-deploy settings—never hardcode in source • strict separation of config from code.
IV. Backing Services	`DATABASE_URL`, `REDIS_URL`, `S3_BUCKET`	• Treat backing services as attached resources—databases, queues, caches, SMTP, APIs accessed via URL/credentials in config • swappable without code changes.
V. Build, Release, Run	Build:`npm run build` → Release:`v123+config` → Run:`node app.js`	• Strict separation of three stages: Build (convert code to executable), Release (combine build + config), Run (execute app in environment) • no code changes at runtime.
VI. Processes	Stateless web workers; state in Redis/DB, not memory	• Execute app as stateless, share-nothing processes • any data that must persist goes to a stateful backing service (DB, cache) • enables horizontal scaling.