TL;DR: it’s a guide with best practices for any engineer who builds & deploys SaaS, based on experience working and scaling many apps on Heroku platform.
In the modern era, software is commonly delivered as a service: called web apps, or software-as-a-service. The twelve-factor app is a methodology for building software-as-a-service apps that:
- Use declarative formats for setup automation to minimize time and cost for new developers joining the project;
- Have a clean contract with the underlying operating system, offering maximum portability between execution environments;
- Are suitable for deployment on modern cloud platforms, obviating the need for servers and systems administration;
- Minimize divergence between development and production, enabling continuous deployment for maximum agility;
- And can scale up without significant changes to tooling, architecture, or development practices.
The twelve-factor methodology can be applied to apps written in any programming language and use any backing services (database, queue, memory cache, etc.).
One codebase tracked in revision control, many deploys. One app, one codebase. Each component maps to one app (or service) in a distributed system.
Explicitly declare and isolate dependencies. Never depends on implicit system-wide packages. Declare all dependencies completely and exactly. Use a dependency isolation tool (virtualenv for Python) to prevent leaks or dirty dependencies.
Store config in the environment. Dev, staging, production environment should have different configs. Separate config from code.
Treat backing services as attached resources, i.e., local and third-party services can be used interchangeably. Resources can be attached/detached at will.
Strictly separate build and run stages. Restrict changes to the code at runtime.
Execute the app as one or more stateless processes. Processes are stateless and share-nothing. This will allow the app to scale horizontally. Any data that needs to persist must be stored in a stateful backing service, typically a database.
Export services via port binding. The app is completely self-contained and does not rely on runtime injection of a webserver into the execution environment to create a web-facing service. The web app exports HTTP as a service by binding to a port and listening to requests coming in on that port.
Scale-out via the process model. In the twelve-factor app, processes are a first-class citizen. Processes in the twelve-factor app take strong cues from the Unix process model for running service daemons. Using this model, the developer can architect their app to handle diverse workloads by assigning each type of work to a process type. For example, HTTP requests may be handled by a web process, and a worker process handles long-running background tasks.
Maximize robustness with fast startup and graceful shutdown. App processes are disposable and can be spun up / spun down easily. App on shutdown should exit gracefully, such as returning job to the queue or closing existing connections upon receiving SIGNTERM.
Keep development, staging, and production as similar as possible.
Treat logs as event streams. The app never concerns itself with routing or storage of its output stream. On localhost, it can be just stdout. On a production system, the streams are captured by a log system.
Run admin/management tasks as one-off processes.
One-off admin processes should be run in an identical environment as the regular long-running processes of the app. They run against a release, using the same codebase and config as any process run against that release. Admin code must ship with application code to avoid synchronization issues.