What Is the Twelve Factor App? 12 Principles, Benefits & Adoption Guide (2026)

A release works on one engineer's laptop and passes in staging, then fails in production because a library version differs, a database address was hard-coded, or a worker kept session data on a disk that vanished when the instance restarted. Each fault looks small, yet together they make deployments slow, rollbacks uncertain and scaling risky. The twelve factor app is a set of twelve practices written to remove exactly those frictions, and it remains a useful checklist for any team that ships software as a service.
TL;DR
Definition: The twelve-factor app is a methodology, written by Adam Wiggins and drawn from Heroku's experience, for building software-as-a-service applications that are portable, deployable and scalable.
Main ideas: Keep one codebase, declare dependencies, store config in the environment, treat databases and queues as attached resources, separate build, release and run, and keep processes stateless and disposable.
Benefits: Repeatable releases, more consistent environments and an easier path to horizontal scaling, though none of these outcomes is guaranteed.
Limitation: It is not a security standard, and it does not require microservices, Docker or Kubernetes. Stateful and specialised workloads need adaptation.
Adoption: Audit first, fix exposed config and dependencies, then builds, state, logs and shutdown behaviour, step by step rather than through a rewrite.
What Is the Twelve Factor App?
The twelve-factor app is a methodology of twelve practices for building software-as-a-service applications that are portable, easy to deploy and able to scale. Written by Adam Wiggins and drawn from experience at Heroku, it covers codebase, dependencies, configuration, backing services, releases, processes, ports, concurrency, disposability, environment parity, logs and admin tasks.
Table of Contents
What Is the Twelve-Factor App?
The twelve-factor app is a methodology for building software that is delivered as a service: web applications, APIs and background workers that run continuously and are deployed many times. Adam Wiggins published it at 12factor.net, and the guidance reflects experience of building and operating applications on Heroku, a platform as a service.
The original text lists its goals plainly. Setup should be automated with declarative formats. The app should have a clean contract with the operating system, so it moves easily between execution environments. It should suit modern cloud platforms, keep development and production close together, and scale without major changes to tooling or architecture.
Two points keep the idea honest. First, it is independent of language and framework, and it applies to apps using any combination of backing services. Second, it is a set of principles rather than a product, a certification or an architecture. A monolith can follow every factor, and a fleet of microservices can break most of them.
The methodology also pre-dates much of today's vocabulary. Containers, Kubernetes, GitOps, OpenTelemetry and software-supply-chain security are not part of the original twelve. This guide keeps the original factors separate from later practices and brings the newer ideas in only where they help. For the wider landscape, see cloud-native architecture and cloud-native development.
Why the Twelve-Factor Methodology Matters
The factors matter because each one removes a specific operational mechanism of failure. Declared dependencies and a separate build stage make a release repeatable. External config lets one artifact run in several environments. Treating databases and queues as attached resources, addressed by connection settings, makes it easier to move between a local service and a managed one.
Stateless processes and a process-based concurrency model make horizontal scaling a matter of running more copies. Fast startup and graceful shutdown make deployments and restarts less disruptive. Logs written to a stream let the platform decide where they go. Together they shorten the path from commit to production and make failures easier to diagnose.
They also help people. A new engineer can read the dependency manifest, start the app with documented commands and see the same behaviour as colleagues. Operations and development teams share one contract for how an app starts, stops and is configured, which supports the collaboration described in DevOps.
Evidence of improvement should come from measurement, not belief. Teams can track delivery metrics such as those defined by DORA: change lead time, deployment frequency, failed deployment recovery time, change fail rate and deployment rework rate. The factors create conditions for better results, but they do not guarantee them.
The 12 Factors at a Glance
The table lists all twelve in their original order, using the names and principles from the original site, with a plain-language reading of each.
Factor | Original Principle | Practical Meaning |
I. Codebase | One codebase tracked in revision control, many deploys | One repository per app, many environments |
II. Dependencies | Explicitly declare and isolate dependencies | Manifest and lockfile, no hidden system packages |
III. Config | Store config in the environment | Deploy-specific values live outside the code |
IV. Backing services | Treat backing services as attached resources | Databases and queues are swappable connections |
V. Build, release, run | Strictly separate build and run stages | Build once, combine with config, then run |
VI. Processes | Execute the app as one or more stateless processes | Durable data lives in backing services |
VII. Port binding | Export services via port binding | The app listens on a configured port |
VIII. Concurrency | Scale out via the process model | Add processes by workload type |
IX. Disposability | Maximize robustness with fast startup and graceful shutdown | Start quickly, stop cleanly |
X. Dev/prod parity | Keep development, staging, and production as similar as possible | Shrink gaps in time, people and tools |
XI. Logs | Treat logs as event streams | Write events to stdout and let the platform route them |
XII. Admin processes | Run admin/management tasks as one-off processes | Migrations run with the same code and config |
1. Codebase — One Codebase, Many Deploys
The twelve-factor app has exactly one codebase tracked in version control, and every deploy of that app, whether production, staging or a developer's machine, runs that same codebase, possibly at different commits. If there are several codebases, they are several apps. Code shared between apps becomes a library, managed through the dependency manifest.
A single source of truth removes doubt about what is running where. A bug fixed once is fixed everywhere, and any deploy can be traced to a commit. Branches and versions may differ between deploys, but the repository does not.
A billing service shows the pattern: one repository produces one artifact, which is promoted from staging to production with only configuration changing. Monorepos need a careful reading. A monorepo can hold several apps if each builds and deploys independently, so the rule concerns apps, not the number of repositories.
The usual violation is drift. Examples are a hand-edited "production" folder, long-lived environment branches whose code diverges, or shared code copied between services instead of packaged.
Verification check: pick any running deploy and trace it to a commit in one repository within minutes. If two environments run code that no single commit describes, the factor is not met. Git-based workflows make that traceability routine.
2. Dependencies — Explicitly Declare and Isolate Dependencies
A twelve-factor app never relies on packages that happen to exist on the host. It declares every dependency, with exact versions, in a manifest, and uses an isolation mechanism so that nothing leaks in from the surrounding system at runtime. The original text extends this to system tools: if the app shells out to a utility, that utility is part of the declared dependencies too.
This turns setup into a repeatable procedure. A new engineer, a build server and a production host all resolve the same versions, so "it works on my machine" loses its main cause.
Take a Python service with a lockfile pinned in version control, installed into a virtual environment or a container image. Containers make system-level packages explicit, and Docker multi-stage builds keep compilers and other build tools out of the final image. Containers are one way to satisfy the factor, not a requirement of the original text. The Python Package Index shows how a public registry fits this model.
Typical violations include unpinned ranges, a tool installed by hand on one server, and imports that work only because a global package happens to be present.
Verification check: on a clean machine or fresh container, run only the documented install and start commands. If the app starts with the lockfile versions and no manual package installs, the factor holds.
3. Config — Store Configuration in the Environment
Config is everything likely to differ between deploys: database addresses, credentials for external services and per-deploy hostnames. The twelve-factor app keeps it strictly apart from code, and the original site offers a simple test: could the codebase be made public without exposing any credentials?
Separation lets one build run in many environments, and it prevents a staging value from being compiled into production. The original text also warns against grouping settings into named environments such as "staging" and "production" in code. Each value should be independently settable per deploy, so the combinations do not multiply as the app grows.
An app might read DATABASE_URL, REDIS_URL and a signing key from environment variables, with the values supplied by the platform at start-up. Environment variables are a delivery mechanism, not a security system. Alone they provide no rotation, access control or encryption. Sensitive values belong in a secrets manager or platform secret store with least privilege and rotation. Kubernetes Secrets are also not a guarantee, since they need encryption at rest and tight access rules.
Common violations are committed .env files and code branching on an environment name.
Verification check: scan the repository and its history for credentials, then run one artifact in two environments, changing only configuration. See also configuration management and cloud-native security.
4. Backing Services — Treat Services as Attached Resources
A backing service is anything the app consumes over the network as part of normal operation: a database, message queue, cache, mail service, object store or third-party API. The twelve-factor app reaches each one through a locator and credentials held in config, and makes no distinction in code between a local service and one run by a vendor.
The benefit is operational freedom. A failing database can be replaced, or a self-run Redis swapped for a managed one, by changing configuration and restarting rather than editing code. Resources can also be attached and detached per deploy.
Consider a service whose DATABASE_URL points at a local PostgreSQL container in development and a managed instance in production. Managed offerings such as database as a service fit this pattern naturally.
"Attached" does not mean "interchangeable". Schema, extensions, SQL dialect, consistency guarantees, latency and failover behaviour differ between engines, so swapping a relational database for another product is a migration, not a setting.
Violations include hard-coded hostnames, uploads written to a fixed local path, and vendor-specific features used without documentation.
Verification check: restore a backup into a second instance, change only the connection setting for a test deploy and restart. The app should work without a code change or rebuild.
5. Build, Release, Run — Separate the Three Stages
The original text splits deployment into three stages. The build stage converts a code commit into an executable bundle, fetching dependencies and compiling assets. The release stage combines that build with a deploy's config. The run stage starts processes from a release. Code is never changed at runtime, and every release carries a unique identifier and is immutable, so a rollback means running an earlier release.
This separation makes changes traceable and recoveries fast. Operators can say exactly which build and which config produced a failure, and they can return to a known state without rebuilding.
A pipeline might build a container image tagged with the commit, then record a release as that image's digest plus a config version. CI/CD tools automate the stages, but automation is not the definition: a script that mutates a server is still one stage. Some modern platforms inject config when a container starts rather than creating a separate release artifact. The principle, an immutable build with a traceable pairing of config, survives that adaptation. See cloud deployment for related practices.
Violations include editing files on a live server, rebuilding separately for each environment and getting different results, and having no record of what is running.
Verification check: identify the current release's build and config version, then roll back to the previous one in a single documented step without rebuilding.
6. Processes — Execute the App as Stateless Processes
Twelve-factor processes are stateless and share nothing. Anything that must persist lives in a stateful backing service such as a database. Memory or local disk may serve as a short-lived scratch area within a single transaction, but the app never assumes that it survives the next request or a restart.
Statelessness lets any instance serve any request, which makes replacement, restarts and scaling routine. It also removes the need for sticky sessions, which the original text advises against in favour of a shared session store.
Picture an app that saves uploads to object storage, keeps sessions in Redis and records orders in PostgreSQL. Killing one instance loses nothing. Note what the factor does not say. A stateless process does not forbid persistent business data; it forbids keeping that data inside the process. Some workloads are inherently stateful, such as databases, caches and certain streaming or game servers. They are better treated as backing services and run with durable storage, which is an adaptation rather than a violation of the app's own design. Related ideas appear in cloud workloads.
Typical violations are uploads written to local disk, in-memory job queues and per-instance sessions.
Verification check: terminate an instance mid-session. The user should continue on another instance without losing data.
7. Port Binding — Export Services Through Ports
A twelve-factor app is self-contained. It does not depend on a web server being injected into the execution environment at runtime. Instead it includes a server library, binds to a port and listens for requests, and the port comes from configuration. Because the app is reached over a URL, it can in turn serve as a backing service for another app.
This gives apps a uniform interface to the platform. A routing layer, whether a reverse proxy or a load balancer, maps public hostnames to the app's port, so the app does not need to know its own public address.
A FastAPI service might run under Uvicorn bound to all interfaces on the port named by an environment variable. Cloud Run follows the same idea: it sets a PORT variable and expects the server to listen on all interfaces, with 8080 as the default, according to its container runtime contract. Platforms that provide the HTTP server themselves, such as many function runtimes, are an adaptation of the factor rather than a contradiction of it, since the platform supplies the listening layer. For background on interfaces, see APIs.
Violations include hard-coded ports, binding only to localhost inside a container, and apps that run only inside a particular application server.
Verification check: start the app with two different PORT values and confirm it responds from outside its container or host on each.
8. Concurrency — Scale Out Through the Process Model
In the twelve-factor model, processes are first-class citizens. Developers assign each kind of work to a process type: web processes handle HTTP requests, worker processes consume a queue, and a scheduler handles timed jobs. Scaling out means running more processes of the right type, rather than making one process ever larger. The operating system or platform manages crashes, restarts and output streams.
This matters because it makes capacity a matter of configuration. A traffic spike calls for more web processes, a backlog calls for more workers, and each type scales independently. Platform features such as replica counts and autoscaling in Kubernetes build on the same idea.
Horizontal scaling is not free, however. It depends on the workload and on state. Adding replicas will not help if the bottleneck is a database connection limit, a lock or a third-party rate limit, and some tasks do not parallelise at all. Vertical scaling remains legitimate for those cases.
Common violations are background jobs run as threads inside the web process and the assumption that more replicas always mean more throughput.
Verification check: in staging, raise the worker count from one to three and confirm that throughput rises without duplicate processing. Then find the next bottleneck using your metrics.
9. Disposability — Fast Startup and Graceful Shutdown
Twelve-factor processes are disposable: they can be started or stopped at a moment's notice. Fast startup, ideally seconds, supports elastic scaling and quick deployments. Graceful shutdown means that on SIGTERM, or the platform's equivalent, a web process stops accepting new requests, finishes those in flight, releases its resources and exits. A worker returns its current job to the queue or completes it.
Platforms impose deadlines. Kubernetes sends a termination signal and, after a configurable grace period, force-kills the container, as described in its pod lifecycle documentation. Cloud Run gives a 10-second window after SIGTERM before SIGKILL, per its container contract. An app that ignores the signal loses requests whenever it is replaced.
Picture a worker sending payment receipts. On SIGTERM it finishes the current message or hands it back, and an idempotency key makes a retried send harmless. Jobs must be safe to repeat, because crashes and redeliveries happen even when shutdown is clean. Slow startup also hurts serverless platforms, which is the problem behind cold starts.
Violations include ignoring signals, running schema migrations during boot and holding job state only in memory.
Verification check: send SIGTERM during a load test. In-flight requests should complete, no jobs should be lost, and the time from launch to readiness should be measured and stay within your target.
10. Dev/Prod Parity — Keep Environments Similar
The original text names three gaps to close. The time gap is how long code takes to reach production. The personnel gap separates those who write code from those who deploy it. The tools gap is the difference between the stack used in development and the one in production. Narrowing them supports frequent, low-risk releases.
Parity means minimising material differences, not buying identical infrastructure. A staging environment can run at lower capacity if it uses the same kinds and versions of services.
A team might run PostgreSQL and Redis locally in containers that match production major versions, deploy the same artifact to a smaller staging environment, and release small changes daily. The classic violation is a lightweight database in development and a different engine in production, so queries behave differently. Mocks that hide queue semantics and a staging environment weeks behind production are other examples.
There are honest limits. Production-scale data and hardware can be too costly, personal data cannot always be copied, and some proprietary services have no local twin. Emulators and contract tests narrow those gaps, and the residual risk should be documented. See cloud environments for more.
Verification check: list each backing service with its type and version in every environment, and measure the time from merge to production. Differences in kind deserve a decision.
11. Logs — Treat Logs as Event Streams
Logs are a time-ordered stream of events collected from the output of running processes. A twelve-factor app never manages log files or routing itself. Each process writes events to standard output, and the execution environment captures the streams, collates them and sends them to an aggregation and analysis system.
This keeps the app simple and leaves storage, retention and search to the platform. In practice, structured logs such as JSON lines with a timestamp, level and correlation ID make events searchable across web and worker processes. Sensitive values such as tokens, passwords and personal data must be scrubbed before they are written.
A FastAPI service might log each request as one JSON line with a request ID that its worker also records. Logs are not the whole picture. Metrics and traces are complementary signals rather than synonyms: OpenTelemetry lists traces, metrics and logs among its signals, and they answer different questions. The cloud telemetry guide explains the wider practice.
Violations include rotating log files on a local disk, secrets in log lines and free-text messages nobody can query.
Verification check: make one request and find its lines from every process using the correlation ID in your central tool. Then search the logs for credential patterns and confirm there are none.
12. Admin Processes — Run Tasks as One-Off Processes
Admin tasks such as database migrations, one-time scripts and console sessions should run as one-off processes in the same environment as the app's regular processes. They use the same codebase, config and release, and the admin code ships with the application code, so the two cannot drift apart. The same dependency isolation applies.
This matters because a script run against production from a laptop, with different versions and config, is a common source of damage. A one-off job running the released image avoids that. Kubernetes expresses the idea as a Job, an object for one-off tasks that run until they complete.
For example, a pipeline might run the migration command as a job from the new release before traffic shifts. Good practice adds idempotence so a re-run does no harm, least-privilege credentials, an audit trail of who ran what and migrations written to be backward compatible so old and new versions can coexist during a rollout. Running migrations on every start of many replicas invites races.
Violations include hand-typed SQL on a production host and one-off scripts that no one reviews.
Verification check: for the last admin task, find who ran it, when, from which release and with what output. Then run it twice in staging and confirm the second run is harmless.
How the 12 Factors Work Together: A Practical Application Example
Follow a fictional order-management SaaS built with Python and FastAPI, PostgreSQL, a Redis queue, a web process and a worker process, shipped as a container image through CI/CD. Every name below is invented for illustration.
A developer pushes a commit to the app's single repository (factor 1). The pipeline installs pinned dependencies and builds an image with a multi-stage Dockerfile (factors 2 and 5), tagging it with the commit. A release step pairs that image with config from the platform's secret store and records a release number (factors 3 and 5). The app reaches PostgreSQL and Redis through URLs (factor 4).
The release declares its process types in a Procfile-style file:
web: uvicorn app.main:app --host 0.0.0.0 --port $PORT
worker: python -m app.worker
release: alembic upgrade headThe web process binds to the configured port (factor 7). The worker consumes jobs, and each type scales separately (factors 6 and 8). The release task runs the migration as a one-off process from the same image (factor 12). Deploy-specific values arrive as variables:
DATABASE_URL=postgresql://app_user:<password>@db.internal:5432/orders
REDIS_URL=redis://cache.internal:6379/0
LOG_LEVEL=infoBoth snippets are illustrative, not tested production code, and the password is a placeholder. Staging runs the same service types and versions at lower capacity (factor 10). Processes start quickly, finish in-flight work on SIGTERM and write JSON events to stdout, where the platform collects them (factors 9 and 11).
Now suppose a release introduces a slow query and error rates rise. The team reads correlated logs, then rolls back by starting the previous release, which needs no rebuild. Jobs in flight return to the queue and are retried safely because handlers are idempotent. A fixed commit then flows through the same path. The factors do not prevent the bug, but they make recovery a routine operation.
Benefits of the Twelve-Factor App
Each benefit below follows from a mechanism and depends on a prerequisite. None is automatic.
Portability: a clean contract with the platform, config in the environment and backing services reached by URL reduce coupling to one host. This assumes that you avoid vendor-specific features without a plan.
Reproducible releases: declared dependencies and immutable builds let the same artifact be promoted between environments. It requires disciplined pipelines and lockfiles.
Faster recovery, where supported: releases tied to identifiers allow a rollback without rebuilding. Data migrations still need backward-compatible design, because code can roll back and data may not.
Maintainability and onboarding: one codebase, documented start commands and consistent config make the app easier to understand. Teams still need to keep documentation current.
Environment consistency: parity shrinks the set of surprises between development and production, within the limits of cost and data privacy.
Scalable process model and automation: stateless, disposable processes allow replicas and automated deployment. Capacity still depends on the database and other shared resources.
Adoption can improve consistency and reliability in suitable circumstances. It does not guarantee lower cost, and extra environments and tooling can raise it.
Limitations, Trade-Offs, and When the Principles Need Adaptation
The methodology was written for apps delivered as a service, and several situations require adaptation. Legacy systems may rely on local files, in-memory sessions or hard-coded paths, so cloud migration work can be substantial and should be staged. Stateful or specialised workloads, such as databases, low-latency trading engines, GPU training jobs or game servers, cannot be fully stateless and need durable storage and careful placement.
Operational overhead is real. Pipelines, secret stores, log aggregation and several environments take effort, a cost that belongs in any estimate of software maintenance. Vendor coupling can also creep in: treating a managed service as an attached resource helps, but proprietary features still create switching costs. Regulated environments add audit, residency and change-control duties that the twelve factors do not address, so see cloud compliance.
The original also leaves much uncovered. It is not a security standard and says little about authentication, supply-chain integrity, data governance, deployment strategies or cost control. Newer practices fill those gaps: infrastructure as code, GitOps, observability, zero trust, software-supply-chain security and platform engineering. They complement the factors without being part of them, and a team can follow all twelve and still have weak security.
Twelve-Factor App vs. Cloud-Native, Microservices, DevOps, and Kubernetes
These terms sit at different levels, so they are not rivals. The twelve-factor app is an application methodology. Cloud native is a broader approach to building and running workloads; the CNCF definition describes practices that let organisations run scalable workloads across public, private and hybrid clouds in a repeatable, automated way. Microservices are an architecture style. DevOps is an organisational practice. Kubernetes is orchestration software.
Concept | What it is | Relation to the twelve factors |
Twelve-factor app | Application methodology | Defines how a single app should behave |
Cloud native | Approach to building and running scalable workloads | Factors are compatible, but not the whole picture |
Microservices | Architecture of small independent services | Services can follow the factors, which are not required |
DevOps | Shared practices between development and operations | Supports release, config and recovery practices |
Kubernetes | Container orchestration platform | One runtime option, not a requirement |
Containers, including Docker, package an app, and serverless platforms run it without managing servers. Both are implementations that can satisfy or undermine the factors depending on use. A monolith can be twelve-factor compliant, and splitting one into microservices does not make it so. For deeper reading, see cloud-native applications and the CNCF's role in the foundation's projects.
How to Adopt the Twelve-Factor App: Step-by-Step
Adoption works best as a sequence of small, measurable improvements rather than a rewrite or a tool purchase. Security-sensitive fixes come first, because they carry the highest risk and often the quickest wins.
Baseline deployment pain. Record lead time, failed deployments, rollback time and incident causes. The engineering manager owns this.
Inventory apps and dependencies. List each app, its runtime, libraries and backing services.
Audit against the 12 factors. Use the scorecard below, one app at a time.
Fix exposed config and secrets. Rotate anything committed and move values to a secret store. This is the first security priority and an early win.
Declare dependencies. Add manifests and lockfiles, and remove hidden host tools.
Standardise builds and releases. Produce one immutable artifact per commit with a release identifier.
Separate state. Move sessions, uploads and queues into backing services.
Improve logs and shutdown. Write structured events to stdout and handle SIGTERM.
Automate tests and release. Developers and platform engineers wire the pipeline together, so cloud automation supports repeatability.
Assess dev/prod parity. Compare service types and versions across environments.
Test a pilot. Choose one moderately important app, not the most fragile one.
Measure results. Compare against the baseline, for example with DORA metrics.
Roll out gradually. Reuse templates and lessons, and keep migrating at the pace the teams can absorb. Cloud adoption guidance covers the organisational side.
Developers change code and config handling, platform or DevOps engineers own pipelines and runtimes, and security sets secret policy. No step requires a vendor or a rewrite.
A Practical 30/60/90-Day Adoption Roadmap
This timeline is illustrative, not a guarantee. Larger estates will take longer.
Phase | Objectives and tasks | Deliverables and owner | Success signals | Risks |
Days 1–30 | Audit apps, rank risks, set a baseline and name an owner | Scorecards and baseline metrics, led by the engineering manager | Every pilot candidate has a score and a risk ranking | Audit stalls without an owner |
Days 31–60 | Pilot config, dependency, release and state fixes, with integration tests | Pilot pipeline and rollback procedure, led by the tech lead | Pilot deploys from one artifact and rolls back cleanly | Hidden state surfaces late |
Days 61–90 | Improve observability and resilience, train teams, measure and expand | Logging standard, shutdown handling and training, led by platform engineers | Metrics improve against the baseline and a second app starts | Tooling grows faster than skills |
Twelve-Factor App Checklist and Maturity Scorecard
Score each factor from 0 to 3: 0 absent, 1 ad hoc, 2 mostly implemented with gaps, 3 consistently implemented and verified. Twelve factors give a maximum of 36. The evidence column shows what a 3 looks like.
Factor | Evidence for a score of 3 |
1. Codebase | Every deploy traces to a commit in one repository |
2. Dependencies | Clean-machine build succeeds from the lockfile alone |
3. Config | No secrets in the repository or history, and one artifact runs in two environments |
4. Backing services | Connection settings change without a code change |
5. Build, release, run | Immutable releases and a documented one-step rollback |
6. Processes | Instances can be killed without data loss |
7. Port binding | The app listens on a configured port and is reachable through routing |
8. Concurrency | Process types scale independently with measured results |
9. Disposability | SIGTERM tests show no lost requests or jobs |
10. Dev/prod parity | Service types and versions match across environments |
11. Logs | Structured stdout events with correlation IDs and no secrets |
12. Admin processes | One-off tasks run from the release, audited and re-runnable |
This is Articsledge's suggested editorial framework, not an official Twelve-Factor certification or a validated industry benchmark. As a rough guide, 0–12 suggests foundational gaps, 13–24 partial adoption, 25–32 strong adoption with gaps and 33–36 consistent practice that still needs re-checking. Critical security or reliability risks override a high number: a score of 0 or 1 on secrets handling or on state for a critical service needs attention whatever the total.
Common Twelve-Factor Implementation Mistakes
Committed credentials: found by scanning history; rotate them and move values to a secret store.
Implicit machine libraries: the build fails on a clean host; declare every dependency.
Environment branches: code diverges by environment; use one branch flow and config for differences.
Ephemeral disks used for persistent data: data vanishes on restart; use object storage or a database.
Assuming services swap seamlessly: changing engines breaks queries; test and plan the migration.
Mutable releases: nobody can say what runs; build once and tag every release.
Unsafe scaling: more replicas worsen a shared bottleneck; find the limit first.
Abrupt termination: deploys drop requests; handle SIGTERM and retry safely.
File-only logs: incidents cannot be searched; stream events to stdout.
Unsuitable parity assumptions: a different database engine in tests hides defects; match service kinds.
Risky one-off migrations: a manual change locks tables; use backward-compatible, reviewed steps.
Believing Docker or Kubernetes meets every factor: a container can still hold secrets and local state; audit the app itself.
Needless microservice decomposition: the app splits before it has clear boundaries; a modular monolith can comply.
When Should Your Organization Adopt the Twelve-Factor App?
Adopt it when the cost of inconsistent deploys is visible: slow releases, fragile rollbacks or scaling that needs heroics. Weigh fit with the app, existing technical debt, staff skills, implementation and running costs, reliability and compliance needs, lock-in risk, the options you keep and the opportunity cost of other work. Incremental, measured adoption beats a reflexive rewrite.
Context | Typical fit | Suggested approach |
Early-stage SaaS | Cheap to build in from the start | Adopt now |
Scaling teams | Release friction grows with headcount | Adopt, starting with builds and config |
Enterprise modernisation | Many legacy apps with mixed state | Adapt app by app, using cloud modernization priorities |
Monoliths | Fully compatible | Adopt incrementally |
PaaS | Often matches the model | Adopt, and verify the details |
Managed containers | Needs config, state and shutdown discipline | Adopt |
Serverless | Some factors are adapted by the platform | Adapt |
Hybrid or multicloud | Portability helps, but adds operating cost | Adapt, and see multi-cloud trade-offs |
Defer adoption for short-lived prototypes and for specialised stateful systems, where a different operating model fits better. Revisit when the system becomes long-lived or shared.
FAQ
What is the twelve-factor app in simple terms?
It is a set of twelve practices for building software that runs as a service. They cover how an app handles its code, dependencies, settings, state, logs and releases so that it can be deployed repeatedly, moved between environments and scaled by running more processes. It is a methodology, not a framework, product or certification.
Who created the twelve-factor app?
Adam Wiggins wrote it, and the guidance reflects experience with applications run on Heroku. It is published at 12factor.net. Later practices such as GitOps, observability and software-supply-chain security came afterwards and are not part of the original twelve.
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 addresses one aspect of how a service is built, configured, deployed and operated. The table near the top of this guide gives the original wording.
Is the twelve-factor app still relevant?
Largely yes, for the problems it targets. Repeatable builds, external config, stateless processes and clean shutdown still matter on containers and managed platforms. It does not cover security, supply-chain integrity or modern observability, so most teams treat it as a foundation and add newer practices around it.
Does it require Docker or Kubernetes?
No. The original methodology names no specific tooling. Docker and Kubernetes are common ways to implement it, but using them does not satisfy the factors automatically. A container can still hold secrets, local state or hard-coded ports, so the app itself needs to be checked.
Can a monolith be a twelve-factor app?
Yes. The factors describe how an app behaves, not how many services exist. A monolith with one codebase, declared dependencies, external config, stateless processes and clean shutdown can follow them fully. Microservices can follow them too, but splitting a system adds operating cost and does not make it compliant.
Does stateless mean the app has no database?
No. Stateless means a process keeps no durable data in its own memory or disk between requests. Business data still persists, but in backing services such as databases, object storage or queues. Any instance can then serve any request, and one can be replaced without losing data.
Are environment variables safe for secrets?
They keep secrets out of code, but alone they provide no rotation, access control or encryption. Use a secrets manager or platform secret store with least privilege, auditing and rotation. Kubernetes Secrets also need encryption at rest and tight access rules, so treat them as a mechanism rather than a guarantee.
What does build, release, run mean?
Build turns a commit into an executable artifact. Release combines that artifact with deploy-specific config and gives it an identifier. Run starts processes from a release. Keeping the stages separate makes releases immutable and traceable, so a rollback means starting an earlier release. CI/CD automates the stages but is not their definition.
Does the methodology guarantee scalability?
No. It makes horizontal scaling easier by keeping processes stateless and separating process types, but results depend on the workload. Shared bottlenecks such as database connections, locks and third-party rate limits still cap throughput, and some tasks do not parallelise. Measure before assuming that more replicas will help.
What are its main limitations?
It is not a security standard, and it says little about observability beyond logs, supply-chain integrity, deployment strategies or cost. Legacy, stateful and specialised workloads need adaptation, and the supporting pipelines, environments and secret stores carry operating cost. It describes one app's behaviour, not a whole system's architecture.
How can a team adopt it incrementally?
Start with a low-risk audit of one app, then fix exposed config and secrets, declare dependencies and standardise builds. After that, separate state and improve logs and shutdown. Pilot on a single app, measure against a baseline and expand gradually. No rewrite or vendor purchase is required.
Key Takeaways
The twelve-factor app is a language-independent methodology for service applications, written by Adam Wiggins and drawn from Heroku's experience.
It is not a requirement for Docker, Kubernetes or microservices, and it is not a security standard.
Config belongs outside the code, but environment variables alone are not secret management.
Processes should be stateless, with durable data held in backing services.
Build, release and run are separate concerns, and immutable releases make rollback straightforward.
Disposability depends on fast startup, graceful shutdown and jobs that are safe to repeat.
Dev/prod parity means minimising material differences, not duplicating production infrastructure.
Logs are one observability signal, and metrics and traces complement them.
Adopt in steps: audit, score, pilot, measure and expand. Benefits are possible, not guaranteed.
Actionable Next Steps
Choose one application and score it with the scorecard in this guide. It is a read-only exercise.
Scan the repository and its history for credentials, and rotate anything you find.
Build the app from the lockfile on a clean machine or container.
Send SIGTERM to a staging instance under load and watch for dropped requests or lost jobs.
Write down the current release and rollback procedure, then test the rollback in staging.
Add structured stdout logging with a correlation ID.
Record baseline delivery metrics, pick a pilot app and schedule a review for 30 days later.
Glossary
Codebase: the version-controlled source for one app, from which all of its deploys come.
Dependency isolation: keeping an app's libraries separate from the host's, so only declared ones are used.
Config: values that vary between deploys, such as database addresses and credentials.
Secret: a sensitive config value, such as a password or key, that needs access control and rotation.
Backing service: a network service the app uses, such as a database, queue or cache.
Build artifact: the executable output of the build stage, such as a container image.
Release: a build combined with config and given a unique identifier.
Stateless process: a process that keeps no durable data between requests.
Port binding: the app listening for requests on a port, instead of relying on an injected web server.
Horizontal scaling: adding more processes or instances to increase capacity.
Disposability: the ability of a process to start and stop quickly and safely.
Graceful shutdown: finishing in-flight work and releasing resources after a termination signal.
Idempotency: the property that repeating an operation produces the same result.
Dev/prod parity: keeping development, staging and production similar in time, people and tools.
CI/CD: automation that builds, tests and delivers changes frequently and repeatably.
Container: a packaged, isolated runtime for an app and its system-level dependencies.
Orchestration (Kubernetes): software that schedules, scales and restarts containers across machines.
Cloud native: an approach to running scalable, automated workloads across cloud environments.
Observability: the ability to understand a system's behaviour from its logs, metrics and traces.
One-off task: a short-lived process, such as a migration, that runs and exits.
Sources & References
The Twelve-Factor App. Adam Wiggins. 12factor.net. n.d. https://12factor.net/
III. Config. Adam Wiggins. 12factor.net. n.d. https://12factor.net/config
XI. Logs. Adam Wiggins. 12factor.net. n.d. https://12factor.net/logs
CNCF Cloud Native Definition v1.1. Cloud Native Computing Foundation. GitHub. Approved 2024-02-26. https://github.com/cncf/toc/blob/main/DEFINITION.md
Pod Lifecycle. Kubernetes. kubernetes.io. n.d. https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/
Secrets. Kubernetes. kubernetes.io. n.d. https://kubernetes.io/docs/concepts/configuration/secret/
Jobs. Kubernetes. kubernetes.io. n.d. https://kubernetes.io/docs/concepts/workloads/controllers/job/
Signals. OpenTelemetry. opentelemetry.io. n.d. https://opentelemetry.io/docs/concepts/signals/
Multi-stage builds. Docker. docs.docker.com. n.d. https://docs.docker.com/build/building/multi-stage/
Container runtime contract. Google Cloud. Cloud Run documentation. n.d. https://docs.cloud.google.com/run/docs/container-contract
DORA's software delivery performance metrics. DORA. dora.dev. n.d. https://dora.dev/guides/dora-metrics/


