# The Twelve-Factor App Methodology Explained
The [Twelve-Factor App](https://12factor.net/) is a set of principles written by engineers at Heroku in 2011 for building software-as-a-service apps that are portable, scalable, and easy to operate on modern cloud platforms. More than a decade later, most of it has aged remarkably well — it's effectively the implicit contract that container platforms and Kubernetes assume your app follows. Let's walk through all twelve.
I. Codebase
*One codebase tracked in version control, many deploys.*
A single app maps to a single repository. The same codebase is deployed to dev, staging, and production — they differ only in configuration, not code. If you have multiple codebases, you have a distributed system, not one app. If multiple apps share code, extract it into a library.
II. Dependencies
*Explicitly declare and isolate dependencies.*
Never rely on system-wide packages being present. Declare everything in a manifest (package.json, requirements.txt, go.mod) and isolate it (virtualenvs, node_modules, vendoring). A new developer — or a fresh container — should get a working app from the manifest alone.
{ "dependencies": { "express": "4.19.2" } }Pinning versions makes builds reproducible.
III. Config
*Store config in the environment.*
Anything that varies between deploys — database URLs, API keys, feature flags — belongs in environment variables, never hardcoded or committed. The litmus test: could you open-source the repo right now without leaking credentials?
DATABASE_URL=postgres://...
REDIS_URL=redis://...
STRIPE_SECRET_KEY=sk_live_...This is the factor most directly responsible for making the same image runnable across environments.
IV. Backing Services
*Treat backing services as attached resources.*
A database, cache, queue, or SMTP service is a resource accessed via a URL in config. Swapping a local Postgres for a managed one should require only a config change — no code change. This decoupling is what lets you attach and detach resources freely.
V. Build, Release, Run
*Strictly separate build and run stages.*
- Build: compile code, fetch dependencies, produce an artifact (an image).
- Release: combine the build with config to produce an immutable, versioned release.
- Run: execute the release.
Releases are immutable and uniquely identified; you can roll back to any prior release. You should never edit code on a running server — that breaks the separation and makes the system unreproducible.
VI. Processes
*Execute the app as one or more stateless processes.*
Processes are stateless and share-nothing. Any data that must persist goes to a stateful backing service (database, object store). Don't rely on in-memory or local-disk state surviving between requests — the next request might hit a different process, and processes can be killed and restarted at any time.
VII. Port Binding
*Export services via port binding.*
The app is self-contained and exposes itself by binding to a port, rather than relying on a runtime injection into a webserver. It speaks HTTP (or another protocol) directly. This is exactly how containers work — your app listens on 0.0.0.0:8080 and the platform routes to it.
VIII. Concurrency
*Scale out via the process model.*
Scale by running more processes, not (only) by making one process bigger. Different workload types map to different process types — web processes handle HTTP, worker processes handle background jobs. This horizontal model is the foundation of autoscaling.
web: node server.js (scale to N replicas)
worker: node worker.js (scale independently)IX. Disposability
*Maximize robustness with fast startup and graceful shutdown.*
Processes should start in seconds and shut down gracefully on SIGTERM — finish in-flight requests, release resources, exit. Fast, disposable processes make scaling, deploys, and recovery from crashes smooth. Crash-only design (assume the process can die at any moment) makes systems resilient.
X. Dev/Prod Parity
*Keep development, staging, and production as similar as possible.*
Minimize the gaps in time (deploy often), personnel (devs deploy their own code), and tools (same backing services everywhere). Using SQLite in dev and Postgres in prod invites "works locally" bugs. Containers and ephemeral environments are largely about closing this gap.
XI. Logs
*Treat logs as event streams.*
The app writes logs to stdout/stderr as an unbuffered stream and doesn't concern itself with storage or routing. The execution environment captures, aggregates, and ships logs to wherever they're analyzed. Apps shouldn't manage log files.
XII. Admin Processes
*Run admin/management tasks as one-off processes.*
Database migrations, data backfills, and console sessions run as one-off processes in an identical environment to the app — same codebase, same config — not as ad-hoc scripts on a random machine.
Where the methodology shows its age
Twelve-Factor predates Kubernetes, serverless, and the modern data-intensive app. Fair critiques:
- Stateless dogma. Factor VI works for stateless web apps but stateful workloads (databases, stateful stream processors) are first-class citizens now, with StatefulSets and persistent volumes.
- Config in env vars only. Large config and secrets are often better served by dedicated secret stores and config maps than a flat env namespace; env vars also leak easily into logs and child processes.
- No guidance on APIs, telemetry, or security. Later efforts like the ["Beyond the Twelve-Factor App"](https://www.oreilly.com/library/view/beyond-the-twelve-factor/9781492042631/) book add factors for API-first design and telemetry.
Even so, an app that follows these factors is dramatically easier to containerize, scale, and operate than one that doesn't.
How this maps to a modern platform
Many factors are enforced for you when you deploy on a cloud platform. PandaStack follows the same contract: config via environment variables (with DATABASE_URL auto-wired when you attach a managed database), build/release/run separation (BuildKit build → image in a registry → Helm release with rollbacks and deploy history), logs as streams (live build and app logs via self-hosted Elasticsearch), and horizontal concurrency (KEDA-driven scaling, scale-to-zero on free tier). Writing a Twelve-Factor app is the surest way to make it portable to any such platform.
References
- [The Twelve-Factor App](https://12factor.net/)
- [Beyond the Twelve-Factor App (O'Reilly)](https://www.oreilly.com/library/view/beyond-the-twelve-factor/9781492042631/)
- [Kubernetes — Pod lifecycle and termination](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/)
- [The Reactive Manifesto](https://www.reactivemanifesto.org/)
- [CNCF Cloud Native definition](https://github.com/cncf/toc/blob/main/DEFINITION.md)
Building a Twelve-Factor app? It'll feel right at home on PandaStack's free tier — config, logs, and scaling handled for you. [Start at dashboard.pandastack.io](https://dashboard.pandastack.io).