TwelveFactorApp
title: Twelve-Factor App type: technique created: 2026-05-21 last_updated: 2026-05-21 related: ["radar/tools/Varlock", "radar/techniques/ServiceLevelObjectives", "radar/techniques/FasterLambdaDevelopment"] sources: ["https://dev.to/kshyun28/a-developers-journal-simplifying-the-twelve-factor-app-25o"] radar_quadrant: Techniques radar_ring: Adopt radar_position: inner
A methodology for building portable, scalable, cloud-native software-as-a-service applications, defined by Heroku engineers in 2011. Twelve discrete principles governing codebase organisation, dependency management, configuration, process design, and operational practices.
| # | Factor | Principle |
|---|---|---|
| 1 | Codebase | One repo tracked in version control; many deploys from the same codebase |
| 2 | Dependencies | Explicitly declared and isolated; no reliance on system-wide packages |
| 3 | Config | Stored in environment variables, not in code or config files committed to the repo |
| 4 | Backing services | Databases, queues, caches treated as attached resources; swappable without code changes |
| 5 | Build, release, run | Strictly separated stages; a release is a build combined with its config |
| 6 | Processes | Stateless and share-nothing; persistent state lives in a backing service |
| 7 | Port binding | Services export functionality via a port; no dependency on an injected web server |
| 8 | Concurrency | Scale out via the process model; horizontal scaling over vertical |
| 9 | Disposability | Fast startup, graceful shutdown; processes are ephemeral and replaceable |
| 10 | Dev/prod parity | Minimise gaps between development, staging, and production environments |
| 11 | Logs | Treat as event streams; write to stdout, let the environment route them |
| 12 | Admin processes | Run management tasks (migrations, REPL) as one-off processes in the same environment |
In practice, three factors are violated most frequently:
Factor 3 (Config): Hardcoded database URLs, API keys in source code, or .env files committed to the repo. The correct pattern — environment variables populated at runtime — is what radar/tools/Varlock enforces with schema-validated declarations.
Factor 6 (Stateless processes): Sessions stored in application memory, uploaded files written to the local filesystem. Both break when the process restarts or scales horizontally. State must live in a backing service (Redis, S3, database).
Factor 11 (Logs): Applications that write log files, manage rotation, or filter their own log output. Twelve-factor apps write to stdout only; the execution environment (Docker, Kubernetes, systemd) handles routing to log aggregators — aligning with the radar/tools/OpenTelemetryCollector model.
The twelve factors predate containers but align naturally with both Docker and serverless:
- Stateless processes (factor 6) map directly to Lambda functions and container replicas.
- Port binding (factor 7) is how containers expose services.
- Disposability (factor 9) is what makes Kubernetes pod restarts safe.
- Dev/prod parity (factor 10) is what radar/tools/Floci achieves for local AWS development.
Twelve-Factor App sits in the Adopt ring of the Techniques quadrant, at inner position. Published by Heroku engineers (2011); the DEV Community article studied on 2023-12-31 is a plain-language summary. The methodology is foundational — it describes baseline design decisions for any cloud-hosted service. Inner Adopt reflects that any new application should be evaluated against the twelve factors from day one, not retrofitted later. Violations of factors 3, 6, and 11 are the most common sources of environment-specific bugs and operational incidents.
