Skip to content

The Twelve-Factor App Methodology

Source identity:

title: "The Twelve-Factor App Methodology"
source_url: https://12factor.net
date_accessed: 2025-09-14
category: Cloud Native
tags: [cloud-native, twelve-factor, microservices, best-practices]

The Twelve-Factor App Methodology

Overview

The Twelve-Factor App methodology is a set of best practices for building modern, scalable, and maintainable applications that are suitable for deployment on cloud platforms. Created by Heroku co-founder Adam Wiggins, these principles enable applications to be portable, resilient, and ready for continuous deployment.

The Twelve Factors

I. Codebase

Principle: One codebase tracked in revision control, many deploys

Best Practices:

  • Single repository per application
  • Multiple deployments (dev, staging, production) from same codebase
  • Different versions may be deployed to different environments
  • Use version control (Git) for all code

Anti-patterns:

  • Multiple apps sharing the same repo
  • Distributed version control across multiple repos for one app
  • Code existing outside version control

II. Dependencies

Principle: Explicitly declare and isolate dependencies

Best Practices:

  • Declare all dependencies explicitly via dependency manifest
  • Use dependency isolation tools (virtualenv, bundler, npm)
  • Never rely on system-wide packages
  • Include dependency declaration with the app

Implementation Examples:

  • Python: requirements.txt or Pipfile
  • Node.js: package.json
  • Ruby: Gemfile
  • Go: go.mod

III. Config

Principle: Store config in the environment

Best Practices:

  • Strict separation of config from code
  • Configuration varies between deploys, code doesn’t
  • Store config in environment variables
  • Never commit secrets or credentials to version control

What Belongs in Config:

  • Database connection strings
  • API keys and secrets
  • Per-deploy values (canonical hostname)
  • Feature flags

IV. Backing Services

Principle: Treat backing services as attached resources

Best Practices:

  • No distinction between local and third-party services
  • Services attachable and detachable via config
  • Database, message queues, caches treated uniformly
  • Ability to swap implementations without code changes

Examples:

  • Databases (PostgreSQL, MySQL)
  • Message queues (RabbitMQ, Amazon SQS)
  • Caching systems (Redis, Memcached)
  • Email services (SMTP, SendGrid)

V. Build, Release, Run

Principle: Strictly separate build and run stages

Three Stages:

  1. Build: Convert code into executable bundle
  2. Release: Combine build with config for specific environment
  3. Run: Launch processes from the release

Best Practices:

  • Releases should be immutable
  • Every release has unique ID (timestamp or version)
  • Releases cannot be mutated once created
  • Easy rollback to previous releases

VI. Processes

Principle: Execute the app as one or more stateless processes

Best Practices:

  • Processes are stateless and share-nothing
  • Persistent data stored in backing services
  • Session state stored in time-expiry datastore (Redis)
  • No sticky sessions or local caching

Benefits:

  • Horizontal scalability
  • Fault tolerance
  • Simple deployment model

VII. Port Binding

Principle: Export services via port binding

Best Practices:

  • App is self-contained
  • Doesn’t rely on runtime injection of webserver
  • Exports HTTP as a service by binding to a port
  • In production, routing layer handles requests

Implementation:

  • Apps directly handle HTTP requests
  • Use libraries like Express (Node.js) or Flask (Python)
  • Can become backing service for other apps

VIII. Concurrency

Principle: Scale out via the process model

Best Practices:

  • Apps handle diverse workloads via process types
  • Processes are first-class citizens
  • Scale horizontally by adding more processes
  • Never daemonize or write PID files

Process Types:

  • Web processes handle HTTP requests
  • Worker processes handle background jobs
  • Clock processes handle scheduled tasks

IX. Disposability

Principle: Maximize robustness with fast startup and graceful shutdown

Best Practices:

  • Processes can be started/stopped at moment’s notice
  • Minimize startup time (few seconds ideal)
  • Shut down gracefully on SIGTERM
  • Handle unexpected termination robustly

Graceful Shutdown:

  • Web: Stop accepting new requests, finish current, then exit
  • Worker: Return current job to queue, then exit
  • Design for crash-only software

X. Dev/Prod Parity

Principle: Keep development, staging, and production as similar as possible

Three Gaps to Minimize:

  1. Time gap: Code written quickly deployed
  2. Personnel gap: Developers who write code deploy it
  3. Tools gap: Same backing services in all environments

Best Practices:

  • Deploy frequently (hours, not weeks)
  • Developers involved in deployment
  • Use same database, queue, cache in all environments
  • Containerization helps maintain parity

XI. Logs

Principle: Treat logs as event streams

Best Practices:

  • App never concerns itself with log storage
  • Write all logs to stdout
  • Execution environment handles log collection
  • In production, logs routed to analysis systems

Log Destinations:

  • Local development: Terminal output
  • Production: Centralized logging service
  • Analysis tools: Splunk, ELK stack, CloudWatch

XII. Admin Processes

Principle: Run admin/management tasks as one-off processes

Best Practices:

  • Run in identical environment as regular processes
  • Against same release/config/codebase
  • Admin code ships with application code
  • Use same dependency isolation

Common Admin Tasks:

  • Database migrations
  • Console/REPL for inspection
  • One-time scripts for data cleanup
  • Scheduled maintenance tasks

Relevance to Modern Development (2025)

Cloud-Native Applications

The twelve-factor methodology remains the foundation for:

  • Kubernetes-deployed applications
  • Serverless architectures
  • Microservices design
  • Container-based deployments

Extensions and Evolution

Modern additions to twelve-factor:

  • API First: Design API before implementation
  • Telemetry: Built-in monitoring and observability
  • Security: Security integrated from the start
  • Documentation: API documentation as code

AI and Automation

In AI-assisted development:

  • Config: AI agents need environment-based configuration
  • Stateless: Agents should be stateless for scalability
  • Logs: Agent decisions logged as event streams
  • Backing Services: LLMs treated as backing services

Application to HELIX Workflow

Direct Applications

The HELIX workflow can incorporate twelve-factor principles:

  1. Codebase: Single repository for workflow definitions
  2. Dependencies: Explicit tool and framework dependencies
  3. Config: Environment-based workflow configuration
  4. Processes: Each phase as a stateless process
  5. Logs: Unified logging across all phases
  6. Admin Processes: Migration and maintenance tasks

Recommendations for HELIX

To align with twelve-factor:

  1. Containerize Phases: Each phase runnable in containers
  2. Environment Config: Store phase configurations in environment
  3. Service Abstraction: Treat AI models as backing services
  4. Stateless Execution: No state between phase executions
  5. Event Streaming: Log all workflow events to stdout
  6. Disposable Processes: Phases can start/stop instantly

Key Takeaways

The twelve-factor methodology provides:

  • Portability: Applications run anywhere
  • Scalability: Horizontal scaling through process model
  • Maintainability: Clear separation of concerns
  • Automation: Ready for continuous deployment
  • Resilience: Robust to failures and changes

These principles are essential for building modern applications that can leverage cloud platforms effectively while maintaining simplicity and reliability. Whether building traditional web applications or AI-assisted development workflows, the twelve factors provide a solid foundation for scalable, maintainable systems.