12-Factor App Principles

Manual chapter explaining how 12-Factor discipline supports scale and maintainability.

Source: content/manual/02-12factor/index.md

12-Factor remains the fastest diagnostic for architectural debt. The language is two decades old, but the principles still explain why services fail to scale, environments drift, or onboarding drags. Use this chapter to translate each factor into concrete modernization tasks for container, serverless, or internal platform environments.

Modern interpretation of the 12 factors

Factor	2020s interpretation	Key instrumentation
Codebase	Monorepos are fine when ownership, branching, and deployment tooling are explicit	Service catalog entries, repo CODEOWNERS
Dependencies	Package manifests and SBOMs enforced in CI; dependency diff alerts gate merges	`npm audit`, `pip-audit`, CycloneDX exports
Config	Secrets managers + GitOps overlays; no `.env` surprises	Vault/SSM integrations, environment parity tests
Backing services	Treat every dependency as swappable; document contracts and failure modes	Service catalog, chaos experiments
Build/release/run	Build once, promote via attestations, record provenance	OCI image signatures, SLSA build metadata
Processes	Stateless by default; explicit documentation for stateful exceptions	`playbooks/stateless-microservices/index.md`
Port binding	Uniform health probes and TLS policies across services	Platform readiness probes
Concurrency	Horizontal scaling with idempotent requests, queue back-pressure	Autoscaler metrics, retry policies
Disposability	Fast start/stop, graceful shutdown hooks, clean queues	`SIGTERM` handlers, queue draining metrics
Dev/prod parity	Ephemeral environments, production-like data slices, GitOps config	Review app pipelines, drift detection
Logs	Structured JSON with correlation IDs, shipped to centralized sinks	Log schema validation, trace sampling
Admin processes	Runbook scripts, chatops tasks—never ad-hoc shell access	Script libraries, approval workflows

Modernization playbook

Assess the estate. Run playbooks/12factor-modernized/checklist.md alongside teams to score each factor per service. Capture evidence links in the service catalog for transparency.
Prioritize remediation. Focus first on factors that create outages or compliance risk (config, dependencies, backing services). Bundle lower-risk factors with roadmap work to reduce context switching.
Design paved roads. Provide templates, dev containers, and documentation that embody the desired 12-factor behaviors. playbooks/developer-onboarding-as-a-service/index.md ensures new hires default to the right patterns.
Enforce through automation. Add CI gates for SBOM freshness, GitOps drift detection, secrets scanning, and startup time checks. Tie failures to actionable runbooks.
Review quarterly. Re-run the checklist, celebrate compliant services, and log exceptions with planned sunset dates.

Anti-pattern watchlist

Long-lived snowflake environments.
Mixed concerns in Helm values (config vs. secrets vs. release metadata).
Unowned templates that block platform updates.
Local caches mistaken for durable stores.
Manual interventions (SSH, database tweaks) lacking scripted equivalents.

Diagnostic decision tree

Symptom	Investigation	Next action
Service fails during autoscaling	Check disposability, process, and backing service factors	Run `playbooks/stateless-microservices/index.md`
Onboarding takes weeks	Inspect config, dependencies, admin processes	Apply onboarding and modernization checklists
Frequent secrets incidents	Evaluate config handling, admin processes	Integrate secrets manager, add CI secret scanning
Long recovery from node loss	Review disposability, concurrency, logs	Add graceful shutdown hooks, structured logging

Complementary assets

playbooks/12factor-modernized/index.md — modernization narrative and roadmap.
playbooks/stateless-microservices/index.md — deep dive into processes/backing services.
playbooks/developer-onboarding-as-a-service/index.md — ensures new services follow paved roads.
Keep a shared glossary for 12-factor terminology so teams speak the same language.
Service catalog metadata — shows remediation progress per service.

References

Original 12-Factor essay (Heroku) for baseline principles.
Thoughtworks Technology Radar on platform engineering practices.
CNCF documentation on GitOps and progressive delivery for modern config patterns.