Twelve-Factor App Methodology Cheat Sheet

Updated 2026-05-28

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—and the project was open-sourced in November 2024 (under CC-BY-4.0) to allow community-driven modernization, with active proposals to add an Identity factor, expand Config beyond env vars, and evolve Logs into full telemetry.

What This Cheat Sheet Covers

This topic spans 18 focused tables and 163 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 18: Security Practices for Twelve-Factor Apps

Table 1: The Twelve Core Factors

The twelve factors form a progression from source control through runtime operations. Mastering all twelve together—not just the obvious ones like Config and Logs—is what produces an app that is genuinely portable, operable, and disaster-resilient.

Factor	Example	Description
I. Codebase	`git clone repo && deploy to dev, staging, prod`	One codebase tracked in version control (Git), with many deploys—same source code runs across dev, staging, and production with different configurations.
II. Dependencies	`package.json`, `requirements.txt`, `Gemfile`, `pom.xml`	• Explicitly declare and isolate all dependencies via a manifest • never rely on system-wide packages • use isolation tools (`virtualenv`, `bundler`, `npm install`).
III. Config	`DATABASE_URL=postgres://user:pass@host/db`	• Store config in environment variables—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 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 (code → executable), Release (build + config), Run (execute 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 • 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), with many deploys—same source code runs across dev, staging, and production with different configurations.
II. Dependencies	`package.json`, `requirements.txt`, `Gemfile`, `pom.xml`	• Explicitly declare and isolate all dependencies via a manifest • never rely on system-wide packages • use isolation tools (`virtualenv`, `bundler`, `npm install`).
III. Config	`DATABASE_URL=postgres://user:pass@host/db`	• Store config in environment variables—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 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 (code → executable), Release (build + config), Run (execute 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 • enables horizontal scaling.