quick reference
Twelve-Factor App Cheat Sheet
Quick reference card for the Twelve-Factor App methodology for building modern cloud-native applications.
Twelve-Factor App Cheat Sheet
The Twelve Factors at a Glance
| # | Factor | One-Liner | Key Practice |
|---|---|---|---|
| I | Codebase | One repo, many deploys | Git + CI/CD |
| II | Dependencies | Explicit & isolated | Package manifests |
| III | Config | Store in environment | Environment variables |
| IV | Backing Services | Treat as attached resources | URL-based configuration |
| V | Build, Release, Run | Strictly separate stages | Immutable releases |
| VI | Processes | Stateless & share-nothing | External session stores |
| VII | Port Binding | Export services via port | Self-contained HTTP server |
| VIII | Concurrency | Scale via process model | Horizontal scaling |
| IX | Disposability | Fast startup, graceful shutdown | Handle SIGTERM |
| X | Dev/Prod Parity | Keep environments similar | Same databases locally |
| XI | Logs | Treat as event streams | stdout, log aggregation |
| XII | Admin Processes | Run as one-off tasks | Same deploy, one-off execution |
Factor-by-Factor Quick Reference
I. Codebase
✓ One codebase per application
✓ Multiple deploys (dev, staging, prod) from same codebase
✓ Shared code goes into libraries (npm, pip, maven)
WRONG: Multiple repos for one app
WRONG: One repo with multiple apps
II. Dependencies
✓ Declare dependencies explicitly
✓ Isolate dependencies from system
NODE: package.json + node_modules
PYTHON: requirements.txt + virtualenv
JAVA: pom.xml + Maven
.NET: *.csproj + NuGet
RUBY: Gemfile + bundle
GO: go.mod + go modules
III. Config
✓ Store config in environment variables
✓ Never commit credentials to code
✓ Config varies per deploy; code doesn't
GOOD:
DATABASE_URL=postgres://user:pass@host:5432/db
API_KEY=sk-xxxx
BAD:
const dbUrl = "postgres://user:pass@host:5432/db"
IV. Backing Services
✓ Treat databases, queues, caches as attached resources
✓ Access via URL stored in config
✓ Swap providers without code changes
EXAMPLE:
Local Dev: REDIS_URL=redis://localhost:6379
Production: REDIS_URL=redis://aws-elasticache:6379
V. Build, Release, Run
BUILD → Compile code, fetch dependencies
Output: Build artifact (Docker image, JAR, etc.)
RELEASE → Combine build + config
Output: Immutable release (tagged, versioned)
RUN → Execute release in environment
Output: Running process
✓ Each release has unique ID (timestamp, version)
✓ Releases are immutable (can't modify, only create new)
✓ Rollback = deploy previous release
VI. Processes
✓ Processes are stateless
✓ Any persistent data in backing service (database, cache)
✓ No sticky sessions
WRONG: In-memory session storage
WRONG: Local file uploads
WRONG: Relying on process memory between requests
RIGHT: Redis for sessions
RIGHT: S3 for file uploads
RIGHT: Treat each request independently
VII. Port Binding
✓ App exports HTTP by binding to port
✓ No external web server runtime injection
✓ Port specified via environment variable
EXAMPLE (Node.js):
const port = process.env.PORT || 3000;
app.listen(port);
VIII. Concurrency
✓ Scale out via process model
✓ Different process types for different work
EXAMPLE:
web=3 # 3 web server processes
worker=2 # 2 background job processes
clock=1 # 1 scheduler process
SCALE: Add more processes, not bigger machines
IX. Disposability
✓ Fast startup (seconds, not minutes)
✓ Graceful shutdown on SIGTERM
✓ Robust against sudden death
GRACEFUL SHUTDOWN:
1. Stop accepting new requests
2. Finish in-flight requests
3. Release resources
4. Exit
X. Dev/Prod Parity
MINIMIZE GAPS:
TIME GAP: Deploy continuously (hours, not weeks)
PERSONNEL: Developers who write deploy it
TOOLS: Same backing services everywhere
SAME IN ALL ENVIRONMENTS:
• Database (Postgres everywhere, not SQLite locally)
• Cache (Redis everywhere)
• Queue (RabbitMQ everywhere)
XI. Logs
✓ Write to stdout only
✓ Don't manage log files in app
✓ Let execution environment handle routing
EXAMPLE (Node.js):
console.log(JSON.stringify({ event: 'user_login', userId: 123 }));
// NOT THIS:
fs.appendFileSync('/var/log/app.log', message);
XII. Admin Processes
✓ Run admin tasks in same environment
✓ Ship admin code with application code
✓ Run as one-off processes
EXAMPLES:
• Database migrations
• Console/REPL sessions
• One-time scripts
EXECUTION:
heroku run rails db:migrate
kubectl exec -it pod -- npm run migrate
docker exec container python manage.py shell
Implementation Checklist
□ I. Codebase: Single Git repository
□ II. Dependencies: Package manifest present
□ III. Config: All config in env vars
□ IV. Backing Services: All services via URLs in config
□ V. Build/Release: CI/CD with immutable artifacts
□ VI. Processes: No local session state
□ VII. Port Binding: Self-contained HTTP server
□ VIII.Concurrency: Process-based scaling
□ IX. Disposability: < 30s startup, graceful shutdown
□ X. Dev/Prod Parity: Docker for local dev
□ XI. Logs: stdout only, JSON format
□ XII. Admin Processes: One-off tasks same deployment
Anti-Patterns to Avoid
| Factor | Anti-Pattern | Correct Approach |
|---|---|---|
| III | Committed .env files | Use secrets management |
| IV | Hardcoded connection strings | Environment-based URLs |
| VI | Local file session storage | Redis/Memcached |
| VI | Sticky sessions | Stateless with external store |
| VII | Apache mod_php style | Self-contained server |
| IX | Long startup sequences | Lazy loading, precompilation |
| X | SQLite locally, Postgres in prod | Same database everywhere |
| XI | Application-managed log files | stdout to log aggregator |
Modern Implementation
Container/Kubernetes Alignment
FACTOR KUBERNETES CONCEPT
---------------------------------------
II Container image dependencies
III ConfigMaps, Secrets
IV Service discovery, external services
V Container images, Helm releases
VI Pods are ephemeral, no persistent storage
VII Container port, Service
VIII Replica count, HPA
IX Readiness/liveness probes
X Same image across environments
XI Container stdout → logging agent
XII Jobs, CronJobs
Serverless Alignment
FACTOR SERVERLESS (Lambda/Functions)
---------------------------------------
VI Functions are inherently stateless
VIII Automatic scaling
IX Fast cold starts critical
XI CloudWatch/Cloud Logging automatic