Best-Practices

The twelve-factor app methodology emerged from Heroku’s experience deploying thousands of applications. These principles create applications that work well in modern cloud environments — containerized, horizontally scalable, and continuously deployed. They’re not arbitrary rules. Each factor solves a real problem. I. Codebase One codebase tracked in version control, many deploys. ✅ m ├ ├ └ ❌ m m m y ─ ─ ─ y y y G a ─ ─ ─ B a a a o p a p p p o p . s d d p p p d g r e : - - - : i c p p s d t l r t e o o a v y d g e u i l t c n o o t g p : i m e s n n t / t a / g i n g , p r o d u c t i o n , f e a t u r e - b r a n c h e s Different environments come from the same codebase. Configuration, not code, varies between deploys. ...

You can write brilliant code that nobody can use because the documentation is impenetrable. Or you can write average code with excellent docs that becomes everyone’s go-to solution. Documentation is a multiplier. These principles help you write docs that work. Know Your Audience Different readers need different docs: Tutorials (learning-oriented): “Follow these steps to build X” For newcomers Hand-holding is okay Complete, working examples Progressive complexity How-to Guides (task-oriented): “How to do X” ...

Configuration management sounds simple until you’re debugging why production is reading from the staging database at 3am. Here’s how to structure configuration so environments stay isolated and secrets stay secret. The Twelve-Factor Baseline The Twelve-Factor App got it right: store config in environment variables. But that’s just the starting point. Real systems need layers. ┌ │ ├ │ ├ │ ├ │ └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ R ─ S ─ E ─ D ─ ─ u ─ e ─ n ─ e ─ ─ n ─ c ─ v ─ f ─ ─ t ─ r ─ i ─ a ─ ─ i ─ e ─ r ─ u ─ ─ m ─ t ─ o ─ l ─ ─ e ─ s ─ n ─ t ─ ─ ─ ─ m ─ ─ ─ E ─ M ─ e ─ c ─ ─ n ─ a ─ n ─ o ─ ─ v ─ n ─ t ─ n ─ ─ i ─ a ─ - ─ f ─ ─ r ─ g ─ s ─ i ─ ─ o ─ e ─ p ─ g ─ ─ n ─ r ─ e ─ ─ ─ m ─ ─ c ─ i ─ ─ e ─ ( ─ i ─ n ─ ─ n ─ V ─ f ─ ─ ─ t ─ a ─ i ─ c ─ ─ ─ u ─ c ─ o ─ ─ V ─ l ─ ─ d ─ ─ a ─ t ─ c ─ e ─ ─ r ─ , ─ o ─ ─ ─ i ─ ─ n ─ ─ ─ a ─ A ─ f ─ ─ ─ b ─ W ─ i ─ ─ ─ l ─ S ─ g ─ ─ ─ e ─ ─ ─ ─ ─ s ─ S ─ f ─ ─ ─ ─ S ─ i ─ ─ ─ ─ M ─ l ─ ─ ─ ─ , ─ e ─ ─ ─ ─ ─ s ─ ─ ─ ─ e ─ ─ ─ ─ ─ t ─ ─ ─ ─ ─ c ─ ─ ─ ─ ─ . ─ ─ ─ ─ ─ ) ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐ │ ┤ │ ┤ │ ┤ │ ┘ ← ← H L i o g w h e e s s t t p p r r i i o o r r i i t t y y Each layer overrides the one below it. Defaults live in code, environment-specific values in config files, secrets in a secrets manager, and runtime overrides in environment variables. ...

Your API will be called wrong. Clients will send garbage. Load will spike unexpectedly. Authentication will be misconfigured. The question isn’t whether these things happen — it’s whether your API degrades gracefully or explodes. Here’s how to build APIs that survive contact with the real world. Input Validation: Trust Nothing Every field, every header, every query parameter is hostile until proven otherwise. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 from pydantic import BaseModel, Field, validator from typing import Optional import re class CreateUserRequest(BaseModel): email: str = Field(..., max_length=254) name: str = Field(..., min_length=1, max_length=100) age: Optional[int] = Field(None, ge=0, le=150) @validator('email') def validate_email(cls, v): # Don't just regex — actually validate structure if not re.match(r'^[^@]+@[^@]+\.[^@]+$', v): raise ValueError('Invalid email format') return v.lower().strip() @validator('name') def sanitize_name(cls, v): # Remove control characters, normalize whitespace v = re.sub(r'[\x00-\x1f\x7f-\x9f]', '', v) return ' '.join(v.split()) Key principles: ...

Learn how to design idempotent APIs that handle duplicate requests safely, making your systems more resilient to network failures and client retries.

Networks fail. Services go down. Databases get overwhelmed. The question isn’t whether your requests will fail—it’s how gracefully you handle it when they do. Naive retry logic can turn a minor hiccup into a catastrophic cascade. Smart retry logic can make your system resilient to transient failures. The difference is in the details. The Naive Approach (Don’t Do This) 1 2 3 4 5 6 7 8 9 # Bad: Immediate retry loop def fetch_data(url): for attempt in range(5): try: response = requests.get(url, timeout=5) return response.json() except requests.RequestException: continue raise Exception("Failed after 5 attempts") This code has several problems: ...

Your container is about to die. It has 30 seconds to live. What happens next determines whether your users see a clean transition or a wall of 502 errors. Graceful shutdown is one of those things that seems obvious until you realize most applications do it wrong. The Problem When Kubernetes (or Docker, or systemd) decides to stop your application, it sends a SIGTERM signal. Your application has a grace period—usually 30 seconds—to finish what it’s doing and exit cleanly. After that, it gets SIGKILL. No negotiation. ...

There’s a subtle but powerful distinction in modern software delivery: deployment is not release. Deployment means your code is running in production. Release means your users can see it. Feature flags are the bridge between these two concepts—and mastering them changes how you think about shipping software. The Problem with Traditional Deployment In the old model, deploying code meant releasing features: 1 2 3 # Old way: deploy = release git push origin main # Boom, everyone sees the new feature immediately This creates pressure. You can’t deploy partially-complete work. You can’t test in production with real traffic. And if something breaks, your only option is another deploy to roll back. ...

The twelve-factor methodology emerged from Heroku’s experience running millions of apps. These principles create applications that deploy cleanly, scale effortlessly, and minimize divergence between development and production. Let’s walk through each factor with practical examples. 1. Codebase: One Repo, Many Deploys One codebase tracked in version control, many deploys (dev, staging, prod). 1 2 3 4 5 6 7 8 9 # Good: Single repo, branch-based environments main → production staging → staging feature/* → development # Bad: Separate repos for each environment myapp-dev/ myapp-staging/ myapp-prod/ 1 2 3 4 5 # config.py - Same code, different configs import os ENVIRONMENT = os.getenv("ENVIRONMENT", "development") DATABASE_URL = os.getenv("DATABASE_URL") 2. Dependencies: Explicitly Declare and Isolate Never rely on system-wide packages. Declare everything. ...