Book 09 · Software ArchitecturePage 46 of 48

Twelve-Factor App

Updated September 30, 20262 min read

In short

A twelve-factor app is a web application built according to twelve practices that make it portable, easy to deploy, and simple to scale in the cloud.

What is a twelve-factor app?

The twelve-factor app is a methodology, first published in 2011, that describes how to build software-as-a-service applications that run well on cloud platforms. It lists twelve factors, or practices, that make an app portable between environments, easy to deploy continuously, and able to scale by running more copies. Although it predates most container tooling, its ideas match how modern platforms expect apps to behave.

The twelve factors are: one codebase tracked in version control with many deploys; explicitly declared dependencies; configuration stored in the environment; backing services, such as databases, treated as attached resources; strictly separate build, release, and run stages; stateless processes; services exposed through port binding; scaling out through the process model; disposability, meaning fast startup and graceful shutdown; dev/prod parity, keeping development and production similar; logs treated as event streams; and admin tasks run as one-off processes. Together they push state, configuration, and environment-specific details out of the code.

Think of a shipping container: because its shape and fittings are standard, any ship, train, or truck can carry it without knowing what is inside. A twelve-factor app is similar, since the same build can run on a laptop, a CI server, staging, or production, with only environment variables changing. That is why the factors are a common checklist for containerized apps, serverless functions, and platform-as-a-service deployments.

The methodology is often confused with microservices, but it is about how any single app is built and run, whether it's a monolith or one of many services. Some advice has evolved: secrets are now often delivered from a dedicated secrets manager rather than plain environment variables, and logs usually flow into an observability pipeline. Treat the factors as strong defaults rather than strict rules.

Key takeaways

Twelve-factor is a methodology for building portable, cloud-ready web apps.
Configuration lives in the environment, not in the code.
Processes are stateless; persistent data lives in backing services such as databases.
The same build artifact is promoted unchanged from staging to production.
Logs go to standard output as event streams for the platform to collect.

Example

A few factors in a Node.js serverjavascript

// Factor III (config): settings come from the environment, not the code
const port = Number(process.env.PORT ?? 3000);
const databaseUrl = process.env.DATABASE_URL; // factor IV: an attached backing service

// Factor VII (port binding): the app serves HTTP itself on the given port
const server = app.listen(port, () => {
  console.log(`listening on ${port}`); // factor XI: logs go to stdout
});

// Factor IX (disposability): shut down gracefully when the platform stops the process
process.on("SIGTERM", () => server.close(() => process.exit(0)));

Readers ask

What are the 12 factors?

They are codebase, dependencies, config, backing services, build-release-run, processes, port binding, concurrency, disposability, dev/prod parity, logs, and admin processes. Each one describes a practice that keeps an app portable and easy to operate in the cloud.

Is the twelve-factor methodology still relevant?

Yes. Container platforms, serverless services, and CI/CD pipelines assume most of its practices, such as config in environment variables, stateless processes, and logs on standard output. Some details, like how secrets are handled, have evolved, but the core ideas remain widely used.

Does a twelve-factor app have to be a microservice?

No. The factors apply to any web application or service, including a monolith. They describe how an app is configured, deployed, and run, not how a system is split into services.