Twelve-Factor App Methodology Cheat Sheet

Updated 2026-05-28

🧠Study flashcards on this topic100 cards · spaced repetition→

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, 100 flashcards. 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

Quick IndexSubscribe to unlock

A jump-to index of every table row in this cheat sheet.

Mind MapSubscribe to unlock

An interactive map of every table and concept in this topic.

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.
VII. Port Binding	`app.listen(process.env.PORT)` → self-contained HTTP server	• Export services via port binding—app is completely self-contained, embeds HTTP server (Tomcat, Jetty, Puma, Uvicorn) • does not rely on runtime injection of a web server.
VIII. Concurrency	`web=4, worker=10, clock=1` (process types, scaled out)	• Scale out via the process model—divide work by process type (`web`, `worker`, `cron`) • run multiple instances of each type • horizontal partitioning for concurrency.
IX. Disposability	Startup:`<3s`, Shutdown:`SIGTERM → drain → exit`	• Maximize robustness with fast startup and graceful shutdown—processes are disposable • handle `SIGTERM` gracefully, stop accepting new work, finish in-flight requests, clean up resources.
X. Dev/Prod Parity	Dev, staging, prod use same OS, same DB, same services	Keep development, staging, and production as similar as possible—minimize time gap (continuous deployment), personnel gap (devs deploy), and tools gap (same backing services).
XI. Logs	`console.log(...)` → stdout → centralized logging (ELK, Splunk, OTEL)	• Treat logs as event streams—app writes unbuffered logs to `stdout`/`stderr` • execution environment routes to centralized log aggregation; modern practice extends this to full telemetry via OpenTelemetry.
XII. Admin Processes	`rails db:migrate`, `python manage.py shell`, one-off scripts	Run admin/management tasks as one-off processes in an identical environment—database migrations, REPL console, data imports—using same codebase, config, and release.

Table 2: Codebase & Version Control Patterns

A single codebase is the foundation of every twelve-factor app; every deployment discipline—CI/CD, branch strategy, monorepo layout—flows from this constraint. Getting codebase scope right prevents subtle coupling problems that surface months later.

Pattern	Example	Description
Single repository per app	One repo for the entire app; branches for features	• Exactly one codebase per app tracked in Git • multiple apps sharing code directly in one repo violates twelve-factor—factor shared code into separately versioned libraries.

The rest of this section is part of the full cheat sheet

Table 3: Dependency Management Techniques

Explicit dependency declaration is one of the most portable wins in twelve-factor: it eliminates "works on my machine" problems by making the full dependency tree reproducible on any machine or CI runner. Modern supply-chain security concerns have added SBOM generation and vulnerability scanning as integral parts of this factor.

Technique	Example	Description
Dependency declaration manifest	`package.json` (Node.js), `requirements.txt` (Python), `Gemfile` (Ruby), `pom.xml` (Java)	• Declares all dependencies completely and exactly—libraries, frameworks, tools with specific versions • never assume system-wide packages exist.

The rest of this section is part of the full cheat sheet

Table 4: Configuration & Environment Variables

The config factor is the most actively debated of all twelve factors. The core principle—config varies per deploy, code does not—is timeless, but the implementation has evolved beyond pure environment variables to include mounted volume secrets, secret references, and GitOps config repos, especially in Kubernetes-native deployments.

Pattern	Example	Description
Environment variables for config	`DATABASE_URL=postgres://...`, `API_KEY=xyz123`, `PORT=8080`	• Stores all config in environment variables—credentials, resource URLs, feature flags • language- and OS-agnostic • easy to change between deploys without code changes.

The rest of this section is part of the full cheat sheet

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.
VII. Port Binding	`app.listen(process.env.PORT)` → self-contained HTTP server	• Export services via port binding—app is completely self-contained, embeds HTTP server (Tomcat, Jetty, Puma, Uvicorn) • does not rely on runtime injection of a web server.
VIII. Concurrency	`web=4, worker=10, clock=1` (process types, scaled out)	• Scale out via the process model—divide work by process type (`web`, `worker`, `cron`) • run multiple instances of each type • horizontal partitioning for concurrency.
IX. Disposability	Startup:`<3s`, Shutdown:`SIGTERM → drain → exit`	• Maximize robustness with fast startup and graceful shutdown—processes are disposable • handle `SIGTERM` gracefully, stop accepting new work, finish in-flight requests, clean up resources.
X. Dev/Prod Parity	Dev, staging, prod use same OS, same DB, same services	Keep development, staging, and production as similar as possible—minimize time gap (continuous deployment), personnel gap (devs deploy), and tools gap (same backing services).
XI. Logs	`console.log(...)` → stdout → centralized logging (ELK, Splunk, OTEL)	• Treat logs as event streams—app writes unbuffered logs to `stdout`/`stderr` • execution environment routes to centralized log aggregation; modern practice extends this to full telemetry via OpenTelemetry.
XII. Admin Processes	`rails db:migrate`, `python manage.py shell`, one-off scripts	Run admin/management tasks as one-off processes in an identical environment—database migrations, REPL console, data imports—using same codebase, config, and release.

Table 2: Codebase & Version Control Patterns

Pattern	Example	Description
Single repository per app	One repo for the entire app; branches for features	• Exactly one codebase per app tracked in Git • multiple apps sharing code directly in one repo violates twelve-factor—factor shared code into separately versioned libraries.

Table 3: Dependency Management Techniques

Technique	Example	Description
Dependency declaration manifest	`package.json` (Node.js), `requirements.txt` (Python), `Gemfile` (Ruby), `pom.xml` (Java)	• Declares all dependencies completely and exactly—libraries, frameworks, tools with specific versions • never assume system-wide packages exist.

Table 4: Configuration & Environment Variables

Pattern	Example	Description
Environment variables for config	`DATABASE_URL=postgres://...`, `API_KEY=xyz123`, `PORT=8080`	• Stores all config in environment variables—credentials, resource URLs, feature flags • language- and OS-agnostic • easy to change between deploys without code changes.