The Twelve-Factor App: A Practical Summary
The twelve factors describe how to build a service that deploys cleanly. Learn each factor and what it means in practice.
By Velloreth
The twelve factors
1. Codebase — one codebase in version control, many deploys. The same code runs in every environment.
2. Dependencies — declare them explicitly and isolate them. No reliance on a system-wide package.
3. Config — store configuration in the environment, not in the code.
4. Backing services — treat a database, a queue, or a cache as an attached resource, swappable by changing a URL.
5. Build, release, run — separate the stages strictly. A release is immutable and identifiable.
6. Processes — run the application as one or more stateless processes.
7. Port binding — the application exports a service by binding to a port, rather than relying on an external server.
8. Concurrency — scale out by running more processes, not by making one process bigger.
9. Disposability — start fast and shut down gracefully, so processes can be replaced at any time.
10. Dev/prod parity — keep development, staging, and production as similar as possible.
11. Logs — treat logs as an event stream, written to stdout.
12. Admin processes — run one-off tasks as separate processes, using the same code and configuration.
The ones that matter most
Config in the environment
The same build runs everywhere, and the environment supplies the differences.
const config = {
databaseUrl: process.env.DATABASE_URL,
port: Number(process.env.PORT ?? 3000),
};
The alternative — a config file per environment — means the build differs between environments, which breaks the guarantee that what you tested is what you deploy.
Stateless processes
A process holds no data that must survive a restart.
Session state goes in a shared store, not in memory.
// Bad: the session is lost when the process restarts
const sessions = new Map();
// Good: a shared store
await redis.set(`session:${id}`, data);
Uploaded files go in object storage, not on the local disk.
// Bad: the file is on one machine
fs.writeFileSync('/tmp/upload.png', buffer);
// Good: object storage
await s3.putObject({ Bucket, Key, Body: buffer });
The payoff: any process can serve any request, so you can add or remove processes freely. This is what makes horizontal scaling and rolling deploys work.
Disposability
Start fast. A process that takes a minute to boot cannot be scaled quickly or restarted cheaply.
Shut down gracefully. On SIGTERM, stop accepting new requests, finish in-flight ones, and exit.
process.on('SIGTERM', async () => {
server.close(async () => {
await db.end();
process.exit(0);
});
});
Without this, a deploy drops in-flight requests.
Logs as a stream
The application writes to stdout; the platform collects it.
console.log(JSON.stringify({ level: 'info', msg: 'started', ts: Date.now() }));
Do not write log files. The application should not manage rotation, and in a container the filesystem is ephemeral.
Use structured logs. JSON is machine-readable, which makes searching and alerting possible.
Build, release, run
Build — compile the code into an artifact.
Release — combine the artifact with configuration.
Run — execute the release.
Each release is immutable and has an identifier, so you can roll back to a specific one. This is what a container image tag gives you.
Where the factors are dated
One codebase per service assumes a service-oriented architecture. A monorepo has one codebase and many services, which the factor does not address.
Port binding is now the default, so the factor is less of a decision.
Dev/prod parity is easier with containers, which the document predates.
The count is arbitrary. The value is in the reasoning, not in having exactly twelve.
Applying them
For a new service:
- One repository, one deployable.
- Dependencies in a lockfile.
- Configuration in environment variables, validated at startup.
- Stateless processes, with state in a shared store.
- Logs to stdout as JSON.
- A container image as the release artifact.
- Graceful shutdown on
SIGTERM.
For an existing service:
- Move configuration out of the code first. It is the highest-value change.
- Then move session state to a shared store.
- Then switch logs to stdout.
- Then add graceful shutdown.
Each step makes the service easier to deploy, and they can be done incrementally.
Backing services
A backing service is anything the application consumes over the network: a database, a queue, a cache, an email service.
The factor says to treat them as attached resources, swappable by changing a URL.
// The same code works for a local database and a managed one
const db = connect(process.env.DATABASE_URL);
The payoff: a local Postgres and a managed Postgres are the same to the application. You can swap one for the other by changing a variable, which makes development, testing, and production more similar.
The anti-pattern is code that branches on which service is in use.
// Fragile: the code knows about the environment
if (process.env.NODE_ENV === 'production') {
useManagedQueue();
} else {
useLocalQueue();
}
The better approach is a common interface, with the implementation chosen by configuration.
Dev/prod parity
The factor asks for development, staging, and production to be as similar as possible.
The gaps that cause bugs:
- Time gap — a change takes weeks to reach production, so the feedback is slow.
- Personnel gap — the developer who wrote the code does not deploy it.
- Tools gap — development uses SQLite and production uses Postgres.
Containers close the tools gap. The same image runs everywhere, so the runtime is identical.
Continuous deployment closes the time gap. A change reaches production in minutes, so a problem is found while the context is fresh.
The pragmatic version: use the same database engine in development as in production, even if the data differs. A SQLite-to-Postgres difference is a class of bug that only appears in production.
Admin processes
One-off tasks — a migration, a console, a data fix — should run as separate processes using the same code and configuration.
# The same image, a different command
docker run --rm myapp npm run migrate
kubectl run migrate --image=myapp -- npm run migrate
Do not run a migration from the application’s startup. It couples the deploy to the migration, and a failed migration leaves the application unable to start.
Do not run an admin task in a long-lived process. A console session that holds a connection open is a resource leak.
The factor is about consistency: the admin process uses the same code, the same dependencies, and the same configuration as the application, so it cannot drift.
Practical guidance
- Configuration in the environment, validated at startup.
- Stateless processes, with state in a shared store.
- Logs to stdout as structured JSON.
- Graceful shutdown on
SIGTERM. - Immutable releases with an identifier.
- Declare dependencies in a lockfile.
- Treat backing services as swappable resources.
- Remember the factors are guidelines, not laws.
For the related guides, see environment-variables-best-practices and docker-basics-guide. For the broader context, logging-best-practices and kubernetes-basics.
Quotable summary
The twelve factors are a set of principles for building a service that is portable and deploys cleanly, published by Heroku in 2011. The core ideas are one codebase, explicit dependencies, configuration in the environment, and stateless processes. A stateless process can be replaced at any time, which is what makes horizontal scaling and rolling deploys possible, so session state goes in a shared store and uploaded files go in object storage. Logs are an event stream rather than a file, so the application writes to stdout and the platform collects it. The factors are guidelines rather than laws, and the value is in the reasoning, not the count.