The Twelve-Factor App Manifesto

The Twelve-Factor Manifesto is intended for:

• Developers building applications that run as a service.
• Ops engineers who deploy or manage such applications.

A twelve-factor app distinguishes between regular business processes (e.g., handling web requests) and one-off administrative or maintenance tasks. Administrative tasks should be treated as separate, ad hoc processes rather than being integrated into the long-running application processes.

Common examples of administrative tasks include:

• Running database migrations (e.g., manage.py migrate in Django or rake db:migrate in Rails).
• Launching a REPL (Read-Eval-Print Loop) shell to execute arbitrary code or inspect models against the live database.
• Executing one-time scripts committed to the repository (e.g., php scripts/fix_bad_records.php).

To comply with the Twelve-Factor methodology, there must be exactly one codebase per app.

• If you have multiple codebases: You are building a distributed system, not a single app. Each component in that system should be treated as an individual app that can independently comply with Twelve-Factor.
• If multiple apps share the same codebase: This is a violation.

How to share code: If multiple apps require shared functionality, do not share a codebase. Instead, factor the shared code into libraries and include them via a dependency manager.

To maintain twelve-factor compliance, an application must never attempt to write to or manage logfiles directly. The responsibility for capturing, routing, and storing log streams belongs entirely to the execution environment.

Benefits of Decoupling

By delegating log management to the environment (using tools like Logplex or Fluentd), you can route streams to various destinations without changing application code, such as:

• Log Indexing and Analysis Systems (e.g., Splunk): For finding specific past events and active alerting.
• Data Warehousing Systems (e.g., Hadoop/Hive): For large-scale graphing of trends like requests per minute.
• Real-time viewing: Using tail in a terminal.
• Long-term archival: Managed by the environment for historical introspection.

Instead of using constants in code or language-specific config files (like config/database.yml), a twelve-factor app stores configuration in environment variables (env vars).

Benefits of environment variables:

• Ease of change: They can be changed between deploys without modifying any code.
• Security: There is little chance of accidentally checking them into revision control.
• Portability: They are a language- and OS-agnostic standard, unlike framework-specific config files or Java System Properties.

To support reliable deployments and rollbacks, every release must be treated as an immutable, append-only entry in a ledger.

• Immutability: Once a release is created, it cannot be modified.
• Uniqueness: Every release must have a unique identifier, such as a timestamp (e.g., 2011-04-06-20:32:17) or an incrementing version number (e.g., v100).
• Changes: Any change to the code or the configuration must result in the creation of an entirely new release.

Avoid grouping configuration into named batches or 'environments' (e.g., development, test, production). Grouping by environment leads to a combinatorial explosion of configuration as you add new deploys like staging, qa, or personal developer environments (e.g., joes-staging).

In a twelve-factor app, environment variables are managed as granular controls that are independently set for each deploy. This model scales smoothly as the number of deploys increases.

To satisfy the Twelve-Factor methodology for dependencies, an application must be built and run in deterministic environments. This involves two critical steps:

1. Explicit Declaration: All dependencies must be declared completely and exactly in a dependency declaration manifest. This allows new developers to set up the environment using only the language runtime and a dependency manager.
2. Isolation: The application must use a dependency isolation tool during execution to ensure that no implicit dependencies from the surrounding system "leak in."

Dependency declaration and isolation must be used together; using only one is insufficient. The same specification must be applied uniformly to both production and development environments.

A twelve-factor app must always be tracked in a version control system. The copy of the revision tracking database is referred to as a code repository (or code repo).

• In centralized systems (like Subversion), a codebase is any single repo.
• In decentralized systems (like Git), a codebase is any set of repos that share a root commit.