Skip to content
Velloreth
Programming 6 min read

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

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.

Frequently asked questions

What is a twelve-factor app?
A set of twelve principles for building a software service, published by Heroku in 2011. They describe how to make an application portable, scalable, and easy to deploy.
What is the most important factor?
Configuration in the environment and stateless processes are the two that most affect deployability. Together they let the same build run anywhere and let processes be replaced freely.
What does stateless mean?
The process holds no data that must survive a restart. Session state goes in a shared store, and uploaded files go in object storage, so any process can serve any request.
Why should logs go to stdout?
Because the application should not manage log files. Writing to stdout lets the platform collect, route, and rotate the logs, which is simpler and works in a container.
Are the twelve factors still relevant?
Yes, and they are more relevant in a container and cloud environment, where portability and statelessness matter most. Some factors are dated, such as the assumption of a single codebase per service.
What is the build, release, run separation?
The build stage compiles the code into an artifact, the release stage combines it with configuration, and the run stage executes it. Each release is immutable and identifiable.