The Twelve-Factor App
The Twelve-Factor App
The Twelve-Factor App methodology is a set of best practices for building modern, scalable, and maintainable software applications. Heroku co-founder Adam Wiggins introduced it in 2011, and it has since become a widely adopted standard for cloud-native development.
The methodology helps developers build applications that are easy to deploy, scale, and maintain. Its guidelines cover everything from codebase organisation to deployment strategies. By following these principles, you can create applications that are more reliable, scalable, and straightforward to operate — all of which remain critical considerations in 2026.
The Twelve Factors
- Codebase
- Dependencies
- Config
- Backing Services
- Build, release, run
- Processes
- Port binding
- Concurrency
- Disposability
- Dev/prod parity
- Logs
- Admin processes
1. Codebase
Maintain a single source of truth for your codebase, typically a version control system such as Git.
The code in your repository should be the same code that runs in production. Different environments (development, staging, production) all deploy from the same codebase.
2. Dependencies
Declare and isolate all dependencies explicitly. Every dependency your application needs should be declared in a manifest and managed by a package manager such as npm, pip, or Composer — never rely on implicit system-level packages.
3. Config
Store configuration that varies between environments in environment variables, not in code. Your application should read values such as database URLs, API keys, and feature flags from the environment at runtime rather than hard-coding them.
4. Backing Services
Treat external services — databases, caches, message queues, email providers — as attached resources. You should be able to swap one backing service for another (for example, switching from MySQL to PostgreSQL) by changing only the configuration, without any code changes.
5. Build, release, run
Keep the build, release, and run stages strictly separate. The build stage converts source code into an executable bundle. The release stage combines that bundle with the current environment's configuration. The run stage starts the application. No stage should reach back and modify a previous one.
6. Processes
Run your application as one or more stateless processes. Each process should be entirely independent; any shared state belongs in a backing service (such as a database or cache), not in the process itself.
This is particularly important in cloud-native and container-based deployments, where horizontal scaling — adding more instances rather than more powerful machines — is the primary way to handle increased load.
7. Port binding
Make your application self-contained by exposing its services via port binding. The application listens on a port defined by the environment, allowing other services or a router to reach it without any external web server being required.
8. Concurrency
Scale out via the process model. Design your application to handle increased load by running more process instances rather than by adding more resources to a single instance.
Background work such as job processing or scheduled tasks should run as separate processes. This keeps your web processes lean and makes each type of work independently scalable.
9. Disposability
Maximise robustness by designing for fast startup and graceful shutdown. A process should be ready to serve requests within seconds of starting and should handle termination signals cleanly, finishing any in-flight work before exiting.
This matters especially in containerised environments, where processes are routinely started and stopped as part of normal scaling and deployment activity.
10. Dev/prod parity
Keep your development, staging, and production environments as similar as possible. Differences between environments are a common source of bugs that only appear at deploy time.
Containerisation tools such as Docker make this straightforward: you package your application and all its dependencies into a single image, ensuring consistent behaviour across every environment.
11. Logs
Treat logs as event streams. Your application should write logs to standard output without worrying about their storage or routing. The execution environment handles log aggregation, and you can then query and analyse them to identify issues and trends. Modern observability platforms (Datadog, Grafana, and similar tools) make this workflow seamless in 2026.
12. Admin processes
Run admin and management tasks — database migrations, cache warming, one-off scripts — as separate, one-off processes that run against the same codebase and environment as the application. They should start, do their work, and exit cleanly.
By following the Twelve-Factor App methodology, you can build applications that are more reliable, scalable, and maintainable. The principles remain as relevant today as they were at their introduction, and they form the foundation of most modern cloud deployment practices.