The 12-Factor App is a set of best practices for building modern, scalable, and maintainable software-as-a-service (SaaS) applications. It was introduced by engineers at Heroku to help teams build applications that are:
- Portable between environments
- Resilient
- Easily scalable
- Maintainable over time
Here are the 12 principles:
1. Codebase — One codebase, tracked in version control, many deploys
- Keep a single repository per app.
- Multiple environments (dev, staging, prod) are just deploys of the same codebase.
2. Dependencies — Explicitly declare and isolate dependencies
- Don’t rely on system-wide packages.
- Use dependency managers like
Maven(Java),npm(Node.js),pip(Python). - Make dependencies explicit and reproducible.
3. Config — Store config in the environment
- Separate config from code.
- Use environment variables for credentials, URLs, feature toggles.
- Avoid hardcoding values.
4. Backing Services — Treat backing services as attached resources
- Databases, queues, caches, or APIs are services, not hardcoded.
- Access them via URLs or environment config so they can be swapped easily.
5. Build, Release, Run — Strictly separate build and run stages
- Build: compile, package assets, create executable.
- Release: combine build + config into a release.
- Run: execute in the runtime environment.
- Never change code in the running environment.
6. Processes — Execute the app as one or more stateless processes
- Don’t store data in memory or local disk that you need later.
- Use external storage (DB, cache, etc.) for persistence.
- Statelessness makes horizontal scaling easier.
7. Port Binding — Export services via port binding
- Self-contained apps should expose an HTTP port directly.
- No need for an external web server like Apache or Nginx inside the same app process.
8. Concurrency — Scale out via the process model
- Run multiple instances for scaling, rather than adding threads inside one big instance.
- Use a process manager or orchestration (Kubernetes, Docker).
9. Disposability — Maximize robustness with fast startup and graceful shutdown
- Apps should start quickly and shut down cleanly.
- Helps in scaling, deployment, and recovery.
10. Dev/Prod Parity — Keep development, staging, and production as similar as possible
-
Reduce the gap in:
- Time (deploy often)
- Personnel (same team in all environments)
- Tools (same dependencies and versions everywhere)
11. Logs — Treat logs as event streams
- Don’t manage log files inside the app.
- Write logs to stdout/stderr, let the environment aggregate/store them.
12. Admin Processes — Run admin/management tasks as one-off processes
- Database migrations, cron jobs, or scripts should run in the same environment/config as the app but as separate one-off processes.
💡 In short: The 12-factor methodology pushes for stateless, portable, and easily deployable applications where configuration is separate, dependencies are explicit, and scaling is easy.