Skip to main content

The Twelve-Factor App: Modern Software Deployment

Summary of: deepresearch/dev-workflow/the-twelve-factor-app-comprehensive-modern-software-deployment.md

Key Points​

  • Origins: Developed at Heroku in 2011, remains foundational for cloud-native applications 15 years later
  • I. Codebase: One repo, many deploys - same code across dev/staging/prod
  • II. Dependencies: Explicit declaration and isolation - never rely on system packages
  • III. Config: Store in environment variables, never in code
  • IV. Backing Services: Treat as attached resources, swappable via config
  • V. Build/Release/Run: Strict separation with immutable releases
  • VI. Processes: Stateless, share-nothing - persist data in backing services
  • VII. Port Binding: Self-contained services export via port
  • VIII. Concurrency: Scale horizontally via process model
  • IX. Disposability: Fast startup, graceful shutdown
  • X. Dev/Prod Parity: Minimize gaps in time, personnel, tools
  • XI. Logs: Treat as event streams, write to stdout
  • XII. Admin Processes: Run as one-off tasks in same environment

Critical Insights​

  1. Start with Factor III (Config) - Environment variables provide immediate security and flexibility benefits
  2. Statelessness (Factor VI) enables everything else - Horizontal scaling, zero-downtime deploys, disaster recovery
  3. Containers naturally enforce many factors - Dependency isolation, port binding, statelessness, disposability

Quick Reference​

FactorPrincipleModern Implementation
I. CodebaseOne repo, many deploysGit + branch strategy
II. DependenciesExplicit + isolatedpackage.json + node_modules
III. ConfigEnvironment variablesConfigMaps/Secrets
IV. Backing ServicesAttached resourcesConnection URLs in config
V. Build/Release/RunImmutable releasesDocker + CI/CD
VI. ProcessesStatelessRedis/DB for state
VII. Port BindingSelf-containedEXPOSE + PORT env
VIII. ConcurrencyHorizontal scalingKubernetes HPA
IX. DisposabilityFast start/stopProbes + preStop hooks
X. ParitySame services everywhereDocker Compose
XI. LogsEvent streamsstdout + log aggregation
XII. AdminOne-off processesKubernetes Jobs

Beyond Twelve Factors (Kevin Hoffman, 2016)​

  • XIII. API First: Design API contract before implementation
  • XIV. Telemetry: Metrics, monitoring, health checks
  • XV. Auth: Security as integral design concern

Kubernetes Mapping​

  • ConfigMaps → Non-sensitive config
  • Secrets → Credentials
  • Deployments → Immutable releases
  • Services → Port binding
  • HPA → Concurrency scaling
  • Probes → Disposability
  • Jobs → Admin processes