But it works on my machine...

“It works on my machine.”

A reassuring sentence… until you’re the person deploying it. 😄

That’s where the 12-Factor App principles come in. They help teams avoid some very familiar headaches.

Settings buried in code.
A dependency installed on someone’s laptop.
Sessions disappearing when a new instance starts.

The name sounds academic. The ideas are pretty practical:

1. Codebase
   One codebase in version control, deployed across environments.

2. Dependencies
   Declare what your app needs. “Ask Dave to install it” doesn’t count.

3. Config
   Keep environment-specific settings outside your code.

4. Backing services
   Treat databases, caches, and queues as attached resources.

5. Build, release, run
   Separate these stages so you know exactly what you’re deploying.

6. Processes
   Keep processes stateless. A user’s session shouldn’t depend on which instance answers.

7. Port binding
   Expose your service through a port.

8. Concurrency
   Scale by adding process instances.

9. Disposability
   Start quickly. Shut down gracefully. Finish or safely hand off work.

10. Dev/prod parity
    Keep environments similar. Fewer “but it worked locally” surprises.

11. Logs
    Emit logs as event streams so your platform can collect and route them.

12. Admin processes
    Run migrations and maintenance tasks using the same code and configuration as your app.

You don’t need to tackle all 12 at once.

Start with the one that keeps causing trouble. Maybe it’s config. Maybe it’s shutdown behavior. Maybe only one person knows how deployments work, and they’re going on holiday. 😅

Which factor has been hardest to get right on your team?