12-factor-app

Community Cloud-Native Applications Best Practices Comprehensive methodology for building modern software-as-a-service applications that are portable, scalable, and maintainable. Contains 51 rules across 12 categories, covering the entire application lifecycle from codebase management to production operations. When to Apply Reference these guidelines when: Designing new backend services or APIs Containerizing applications for Kubernetes or Docker Setting up CI/CD pipelines Managing configuration across environments Implementing logging and monitoring Planning application scaling strategy Debugging deployment or environment issues Rule Categories by Priority Priority Category Impact Prefix 1 Codebase & Version Control CRITICAL code- 2 Dependencies CRITICAL dep- 3 Configuration CRITICAL config- 4 Backing Services HIGH svc- 5 Build, Release, Run HIGH build- 6 Processes & State HIGH proc- 7 Concurrency & Scaling HIGH scale- 8 Disposability HIGH disp- 9 Port Binding MEDIUM port- 10 Dev/Prod Parity MEDIUM parity- 11 Logging MEDIUM log- 12 Admin Processes MEDIUM admin- Quick Reference 1. Codebase & Version Control (CRITICAL) code-single-codebase - Maintain one codebase per application in version control code-one-app-one-repo - Enforce one-to-one correlation between codebase and application code-deploys-not-branches - Use deploys not branches to represent environments code-shared-as-libraries - Factor shared code into libraries managed by dependency manager 2. Dependencies (CRITICAL) dep-explicit-declaration - Declare all dependencies explicitly in a manifest file dep-isolate-execution - Isolate dependencies to prevent system package leakage dep-no-system-tools - Never rely on implicit system tools being available dep-deterministic-builds - Use lockfiles for deterministic dependency resolution 3. Configuration (CRITICAL) config-separate-from-code - Strictly separate configuration from code config-use-env-vars - Store configuration in environment variables config-no-env-groups - Treat environment variables as granular controls not grouped environments config-validate-on-startup - Validate required configuration at application startup config-never-commit-secrets - Never commit secrets or credentials to version control 4. Backing Services (HIGH) svc-as-attached-resources - Treat backing services as attached resources svc-connection-strings - Reference all backing services via connection URLs in config svc-no-local-vs-remote - Make no distinction between local and third-party services svc-detach-attach-without-code - Design services to be detachable and attachable without code changes 5. Build, Release, Run (HIGH) build-separate-stages - Strictly separate build, release, and run stages build-immutable-releases - Create immutable releases with unique identifiers build-no-runtime-changes - Never modify code at runtime - changes require new release build-complexity-in-build - Push complexity into build stage keep run stage minimal build-artifact-per-commit - Generate one build artifact per commit deploy same artifact everywhere 6. Processes & State (HIGH) proc-stateless-processes - Execute the application as stateless processes proc-no-sticky-sessions - Never use sticky sessions - store session data in backing services proc-no-local-filesystem - Never assume local filesystem persists between requests proc-compile-at-build - Perform asset compilation and bundling at build time not runtime proc-share-nothing - Design processes to share nothing with each other 7. Concurrency & Scaling (HIGH) scale-process-model - Scale out via the process model with multiple process types scale-process-types - Assign workloads to appropriate process types scale-no-daemonize - Never daemonize or write PID files let process manager handle it scale-horizontal-not-vertical - Design for horizontal scaling over vertical scaling scale-process-formation - Define process formation as declarative configuration 8. Disposability (HIGH) disp-disposable-processes - Design processes to be disposable started or stopped at any moment disp-fast-startup - Minimize startup time to enable rapid scaling and recovery disp-graceful-shutdown - Implement graceful shutdown on SIGTERM disp-crash-only - Design for crash-only software that recovers from sudden death disp-idempotent-operations - Make operations idempotent to safely retry after failures 9. Port Binding (MEDIUM) port-self-contained - Make the application completely self-contained with embedded server port-export-via-binding - Export services via port binding using PORT environment variable port-any-protocol - Use port binding to export any protocol not just HTTP 10. Dev/Prod Parity (MEDIUM) parity-minimize-gaps - Minimize gaps between development and production environments parity-same-backing-services - Use the same type and version of backing services in all environments parity-deploy-frequently - Deploy frequently to minimize the time gap parity-developers-deploy - Involve developers in deployment to minimize personnel gap 11. Logging (MEDIUM) log-event-streams - Treat logs as event streams not files log-no-routing - Never route or store logs from within the application log-structured-format - Use structured logging for machine-readable event streams log-unbuffered-stdout - Write logs unbuffered to stdout for real-time streaming 12. Admin Processes (MEDIUM) admin-one-off-processes - Run admin tasks as one-off processes not special scripts admin-same-environment - Run admin processes against a release with same codebase and config admin-repl-access - Provide REPL access for debugging and data inspection How to Use Read individual reference files for detailed explanations and code examples: Section definitions - Category structure and impact levels Rule template - Template for adding new rules Reference Files File Description references/_sections.md Category definitions and ordering assets/templates/_template.md Template for new rules metadata.json Version and reference information