The Twelve-Factor App — Source Breakdown

The Twelve-Factor App is Adam Wiggins's compact methodology for applications delivered as services. The canonical EPUB package dates to 2012; the public site identifies the text as last updated in 2017. That makes it a primary source for what twelve-factor means, but not a current specification of cloud-native production readiness.

The document's durable contribution is a set of operational boundaries:

• source identity is separate from deploy identity;
• dependencies are explicit instead of leaking from the host;
• deploy-varying configuration is outside the code and build;
• a build becomes an immutable release before it runs;
• application processes do not own durable state;
• the platform supervises processes, routes ports, and captures output;
• one-off administrative work runs from the same release as normal work.

Those boundaries reduce hidden inputs. A process can be replaced because persistent data is elsewhere; a release can be reproduced because its code and dependencies were fixed before runtime; an environment can change without rebuilding because deploy configuration is separate. The factors reinforce one another rather than acting as twelve independent style rules.

What the source explains especially well #

The strongest chapters are Build, release, run, Processes, Disposability, and Admin processes. Together they give a causal deployment model: create an immutable build, combine it with deploy configuration to name a release, launch supervised processes, and run maintenance against that exact release. The source also correctly makes reentrancy or idempotency a consequence of workers being interruptible and jobs being returned to a queue.

The three original diagrams are information-bearing:

1. one codebase maps to several deploys;
2. code becomes a build, then combines with config to produce a release;
3. process types express workload diversity while process counts express scale.

Their concepts are retained in the GTK synthesis, but the article uses one independent diagram that makes the modern artifact digest, state, telemetry, and one-off job boundaries explicit.

Where a literal reading no longer holds #

• One codebase per app predates mainstream monorepos. The durable requirement is traceable source and independently versioned deployables, not one repository.
• Config in environment variables usefully forbids config baked into code, but environment variables are only one transport. Mounted files, configuration APIs, and secret stores can preserve the same separation. Environment-derived values are normally fixed for a process lifetime, so rotation or reload behavior must be designed explicitly.
• Backing services are swappable by changing a handle is true only behind a compatible semantic contract. PostgreSQL and SQLite, or two queue implementations, differ in transactions, locking, ordering, retries, and failure behavior even when an adapter exposes the same methods.
• Stateless processes means replaceable compute processes do not own durable state. It does not make stateful workloads illegitimate, nor does it specify backup, restore, consistency, schema migration, retention, or disaster recovery.
• Logs to stdout is a transport boundary, not an observability system. Structured events, correlation identifiers, metrics, traces, retention, access control, and alerting remain separate responsibilities.

Material omissions for a modern production review #

The methodology does not define readiness, liveness, startup probes, resource requests and limits, workload identity, authorization, secret encryption and rotation, artifact signing, provenance, vulnerability management, progressive delivery, telemetry correlation, or the lifecycle of stateful data. A twelve-factor service can satisfy every original factor and still be insecure, unobservable, or operationally unsafe.

Current platform specifications sharpen the original model:

• OCI images are content-addressed artifacts, and a digest names exact bytes rather than a mutable tag.
• SLSA provenance records where, when, and how an artifact was produced.
• Kubernetes distinguishes replaceable Deployments, stable-identity StatefulSets, and run-to-completion Jobs.
• Kubernetes treats startup, readiness, and liveness as different signals, and warns that a bad liveness probe can create cascading failures.
• Kubernetes Secrets require encryption-at-rest and least-privilege controls; base64 encoding alone is not confidentiality.
• OpenTelemetry's log model adds structured bodies, severity, resources, and trace/span correlation to the raw event stream.

Archival record #

The canonical EPUB downloaded from https://12factor.net/12factor.epub on 2026-08-21 had SHA-256 bd6860d4dc9f0679992142e244f9f76f702a7b5909814b2cddb4bce3413cc1ee. GTK stores a complete 16-page A4 PDF conversion because the library renderer currently labels archived files as PDFs. The conversion preserves all 13 chapters and three diagrams. Two tables in chapter X were malformed as concatenated text in the EPUB and were restored to tabular layout without changing their visible data. The archived PDF has SHA-256 4e6b23450df3a1eafa2bec46e9b7e7c5c64cbd8a4b46f638aa42a31c30d4d29e.