The twelve-factor methodology is a set of guidelines for building software-as-a-service applications, written well before containers and managed cloud services became standard. Most of it still holds; some of it now describes problems the platform solves for you.
Key takeaways
- The Twelve-Factor App is a methodology, published as a short web document, that lists twelve practices for building portable, deployable web services.
- It was written in the era of platform-as-a-service hosting, and several factors describe constraints that container orchestrators and managed platforms now handle by default.
- The factors covering configuration, backing services, statelessness and logging remain the most directly useful to modern teams.
- Discussion of the methodology resurfaces periodically on developer forums, usually around whether it has aged well rather than around any new release.
- Treating the twelve factors as a checklist to audit an existing service is more productive than treating them as rules that must be satisfied literally.
What is the twelve-factor methodology?
The Twelve-Factor App is a short document describing twelve practices for building web-facing services that are straightforward to deploy, scale and hand over between teams. Each factor is a single principle with a name and a paragraph or two of explanation: store configuration in the environment, treat backing services as attached resources, keep processes stateless, treat logs as event streams, and so on.
The document is not a specification, a standard or a piece of software. It has no compliance body and no test suite. It reads as a distillation of operational experience from running many applications on shared infrastructure, and it is written in the imperative: do this, avoid that. That directness is part of why it spread, and part of why it attracts criticism.
The twelve factors cover, broadly: source control and codebase-to-deploy mapping; explicit dependency declaration; configuration held outside the code; backing services as swappable attachments; separation of build, release and run stages; running the app as stateless processes; exporting services via port binding; scaling out via a process model; fast startup and graceful shutdown; keeping development and production environments similar; logging to standard output; and running administrative tasks as one-off processes.
Why is it being discussed again?
Posts about the methodology circulate on developer aggregator sites at intervals, and the surrounding comment threads tend to follow a familiar shape: some readers describe it as foundational, others as dated. The current round of attention appears to be a discussion thread rather than an announcement, and there is no verified information here about a new edition, a revision or an official update to the original text.
What can be said is that the questions raised are consistent. Developers who started their careers on container platforms encounter the document and find parts of it obvious, because their tooling already enforces those parts. Developers who worked before those platforms existed remember why the advice was written. The disagreement is mostly about whether describing something the platform now does automatically counts as the advice being obsolete or the advice being successful.
The background a newcomer needs
The methodology comes from an era when deploying a web application typically meant configuring a server, installing dependencies onto it, and hoping the resulting machine could be reproduced if it failed. Platform-as-a-service offerings emerged to remove that work: you pushed code, the platform built and ran it, and it handled the routing, restarts and scaling. To make that possible, the platform had to impose constraints on how applications behaved.
Several factors are direct expressions of those constraints. “Store config in the environment” exists because a platform can inject environment variables into a container but cannot know about a config file baked into a build artefact. “Treat logs as event streams” exists because an application writing to a local file on an ephemeral machine loses those logs when the machine goes away. “Processes are stateless” exists because a platform that can kill and restart your application at any moment cannot preserve in-memory session data for you.
Understanding this origin makes the document easier to read. It is not abstract architectural theory. It is a description of what an application must do in order to be safely operated by something other than the person who wrote it.
Who is affected, and how?
Teams building conventional web services and APIs are the intended audience, and for them most of the advice still applies with little translation. If a service reads its database URL from an environment variable, writes structured logs to standard output, holds no session state in process memory and starts in a few seconds, it will behave predictably under almost any modern deployment system.
Teams building other kinds of software have a harder time mapping it. Long-running stateful systems, databases, machine-learning training jobs with large model artefacts, desktop applications, mobile clients and event-driven functions all sit awkwardly against factors that assume a stateless request-handling process. The methodology does not claim to cover these cases, but it is sometimes applied to them anyway, which produces friction.
Platform and infrastructure teams occupy a middle position. Many of the factors are now things they provide rather than things application developers must implement: secret injection, log aggregation, health checking, graceful shutdown handling and process supervision are typically platform features. For those teams the document functions less as a to-do list and more as a description of the contract between platform and application.
Where informed people disagree
The most common criticism is that the configuration factor is too blunt. Environment variables are convenient for a handful of values but awkward for structured configuration, and they have known weaknesses as a mechanism for secrets, since child processes inherit them and they can leak into logs and crash dumps. Many teams now use dedicated secret-management systems, which arguably still satisfies the spirit of the factor while ignoring its letter.
A second area of disagreement concerns dependencies and reproducibility. The factor on explicit dependency declaration predates the widespread adoption of lockfiles and container images, and some argue that a container image already satisfies the goal more completely than any language-level manifest can. Others counter that an image without a reproducible build is a black box, and the factor’s underlying point survives.
A third argument is about scope. Critics note that the twelve factors say little about observability beyond logs, nothing about metrics or distributed tracing, and nothing about the operational concerns that dominate distributed systems: retries, timeouts, backpressure, idempotency and partial failure. Various extended lists have been proposed by different authors over the years to fill these gaps. None has the recognition of the original, and there is no single agreed successor.
Defenders argue that the narrow scope is the point. A document that tried to cover everything would not be memorable enough to be useful, and the twelve factors work precisely because they are few and blunt.
What does this mean in practice?
The practical use is as an audit. Take an existing service and work through the factors as questions rather than commandments. Where does configuration come from, and does it differ between environments in ways that are not visible? What happens if two instances of this process run simultaneously? What happens if one is killed mid-request? Where do the logs go, and who can read them a week later? How long does a cold start take? Can a new developer run this locally without a written runbook of manual steps?
Failing a factor is not automatically a defect. A service that writes to local disk may be doing so deliberately and correctly. The value is in noticing that the choice was made, and confirming it was made on purpose rather than by accident.
For new projects the factors are best treated as defaults to depart from consciously. Starting stateless and adding state where genuinely required is easier than removing accidental state later. Starting with externalised configuration avoids a rewrite when a second environment appears.
What to watch next
There is no announced revision of the original document that can be verified here, so the thing to watch is not a release but a drift: how much of the methodology continues to be absorbed into platform defaults rather than application code. Each time a platform takes over a responsibility — log shipping, secret delivery, shutdown signalling — the corresponding factor becomes less something a developer implements and more something a developer relies on.
The gaps are also worth watching. Distributed-systems concerns and observability beyond logging remain outside the document’s scope, and whether any extended formulation gains broad adoption is an open question. For now, the reasonable position is to use the twelve factors for what they cover well and to look elsewhere for the rest.
Frequently asked questions
Is the Twelve-Factor App still relevant?
Largely yes, though relevance varies by factor. The principles concerning configuration, statelessness, backing services and logging map cleanly onto modern deployment practice and remain useful when reviewing a service. Factors that describe platform mechanics are often already handled by container orchestrators, which makes them feel obvious rather than wrong. The methodology is best used as a review checklist rather than a set of rules to satisfy literally.
Do I need to follow all twelve factors?
No. The factors are guidelines, not requirements, and there is no certification or compliance check attached to them. Some applications have legitimate reasons to depart from several of them, particularly stateful systems and anything that is not a request-handling web service. The useful discipline is to know which factors your application does not follow and to be able to explain why that decision was made.
Does using containers mean my app is twelve-factor?
Not automatically. Containers make some factors easier to satisfy, particularly around dependency isolation and environment parity, but they do not prevent an application from writing state to local disk, reading configuration from a baked-in file or logging to a file inside the container. The packaging format and the application’s behaviour are separate concerns, and only the latter is what the factors describe.
What are the main criticisms of the methodology?
Common criticisms are that environment variables are a poor mechanism for structured configuration and for secrets, that the dependency factor predates lockfiles and container images, and that the document covers logging but not metrics or tracing. Critics also note it says little about the failure modes specific to distributed systems. Defenders argue the narrow scope is deliberate and is what makes the list memorable and usable.
Where can I read the original twelve factors?
The methodology is published as a free web document consisting of a short introduction and one page per factor. It is written in plain language and can be read in full in well under an hour, which is a reasonable use of time before forming a view on it. Several translations exist. The document is short enough that summaries tend to lose the reasoning that makes each factor make sense.
Is there an updated or extended version?
Various authors have proposed extended lists over the years, adding factors covering areas such as telemetry, authentication and API design. These are independent proposals rather than official revisions, and none has achieved comparable recognition. There is no verified information here about an official update to the original document, so any claim of a new authoritative edition should be checked against the source directly.
Sources and further reading
- The original twelve-factor methodology website, which publishes the full text of all twelve factors and remains the primary reference.
- Developer news aggregators, where recurring discussion threads capture practitioner disagreement about which factors have aged well.
- Documentation from container orchestration and platform-as-a-service providers, which describes how configuration, logging and process lifecycle are handled by the platform.
- General software architecture literature on distributed systems and operational practice, which covers the areas the methodology does not address.
Surfaced from the hackernews signal “software methodology discussion”. AI-assisted draft, editorially reviewed.
