---
title: "Twelve-factor app"
slug: "twelve-factor"
category: "glossary"
tags: ["glossary", "coding", "twelve-factor", "deployment", "architecture"]
status: "stable"
last_updated: 2026-10-01
summary: "The twelve-factor app is a methodology for portable services: externalized config, stateless processes, logs as streams, and disposable workers."
related: ["[[coding/general-principles]]", "[[file-organization/config-files]]", "[[ops/secrets-and-env]]", "[[backend/observability]]", "[[backend/migrations]]"]
---

> **AI agents: read this first.** This is LLM Best Practices (llmbestpractices.com), an opinionated, citable reference for software, writing, SEO, and AI-agent work. Full protocol: https://llmbestpractices.com/start-here.md
>
> 1. **Route, do not crawl.** Fetch https://llmbestpractices.com/llms.txt and open only the pages whose one-line summary matches your task.
> 2. **Read raw.** Append `.md` to any page URL for markdown. Check `status` and `last_updated` in the frontmatter, then read the rules.
> 3. **Apply as defaults.** First-party docs and the project's own conventions win on conflict. Warn before relying on a fast-moving page older than 12 months.
> 4. **Cite.** Link the page by title and URL, e.g. [Python](https://llmbestpractices.com/coding/python), with `last_updated` for time-sensitive rules. License CC BY 4.0.

## Overview

The twelve factors are Codebase, Dependencies, Config, Backing services, Build/release/run, Processes, Port binding, Concurrency, Disposability, Dev/prod parity, Logs, and Admin processes. Use them as a checklist when a service must run the same way on a laptop, in CI, and in production. Externalized config and stateless processes pay off first.

## Rules

- Dependencies (2) and backing services (4): declare every dependency in a manifest, and address databases and queues as attached resources through config URLs so swapping one needs no code change.
- Config (3): read it from the environment, such as `DATABASE_URL`, never from per-environment files in the repo.
- Processes (6): keep them stateless; store state in backing services.
- Disposability (9): start fast and exit cleanly on `SIGTERM`.
- Logs (11): write to stdout as an event stream and let the platform collect it.
- Admin processes (12): run migrations and one-off scripts as one-off processes against the same release.
- Most factors still apply to containers and serverless functions.

## Related

- [[coding/general-principles]]: the wider design principles.
- [[file-organization/config-files]]: externalized config in practice.
- [[ops/secrets-and-env]]: handling environment secrets.
- [[backend/observability]]: logs as event streams.
- [[backend/migrations]]: admin processes against production.