Skip to main content

How to Design an Application That Runs Easily on Any Cloud?

A practical guide to the 12-Factor App principles: codebase, dependencies, config, backing services, stateless processes, logs, and more, with diagrams.

Hossam Fares
Share
How to Design an Application That Runs Easily on Any Cloud?

The 12-Factor App is a recipe for apps that run on any cloud without surprises. Engineers at Heroku wrote it after deploying thousands of applications. Below are the 12 factors in plain words, each with a real example.


I. Codebase

One Principle: Each App Has a Single Repository

Every application should have a single Codebase tracked in a version control system (like Git). If an application uses multiple repositories, it’s considered a Distributed System, where each component is a separate service.

  • Why?
    • Simplifies tracking changes.
    • Makes error management easier.
    • Supports Continuous Deployment independently.
  • Practical Example: If you have a web app and an API, keep each in its own repository, not in a single Mono Repo.
  • Note: With all due respect to Mono Repo fans, the 12-Factor App prefers separation for flexibility 😊.

One codebase deployed to production, staging and developer environments

II. Dependencies

Declare and Isolate Dependencies Clearly

Every application should explicitly declare its dependencies in a separate file, like requirements.txt for Python or package.json for Node.js. Avoid uploading dependency files to the repository using .gitignore.

  • Why? Keeps the code clean and allows any application version to be installed in any environment without issues.
  • Practical Example: For Python, list all required libraries in requirements.txt. For Node.js, use package.json. This ensures easy setup in any new environment.

package.json listing the app's dependencies and dev dependencies

III. Config

Store Configuration in Environment Variables

Any configuration that varies between environments (e.g., database connection strings or API keys) should be stored in Environment Variables, not hard-coded in the application.

  • Why?
    • Simplifies changing settings without modifying code.
    • Enhances security by keeping secrets out of the code.
    • Ensures compatibility across environments.
  • Practical Example: If your Development environment uses a local database and Production uses a cloud database, you only need to update the Environment Variables. No code changes required.

App reading configuration from environment variables

IV. Backing Services

Treat Backing Services as Attached Resources

Any external service an application depends on (e.g., database, cache, or external API) should be treated as an Attached Resource.

  • Why? If you switch services (e.g., from a local MySQL to Amazon RDS), you only need to update the configuration, not the code.
  • Practical Example: In development, you might use a local MySQL. In production, you might use a managed MySQL like Amazon RDS. The app works in both without code changes.
    Deploy attached to MySQL, Amazon S3, an email service and Twitter as resources

V. Build, Release, Run

Separate Build, Release, and Run Stages

Continuous Deployment in the 12-Factor App consists of three independent stages:

  1. Build: Compile the application with all dependencies and assets to produce a ready Artifact.
  2. Release: Deploy the Artifact to the target environment.
  3. Run: Launch the new version and route traffic to it.
  • Why? Separation ensures that errors in one stage halt the process, making the system Fail-safe.
  • Practical Example: If an error occurs during the Build stage, no version is deployed to Production, reducing issues.

Build, release and run stages driven by continuous delivery

VI. Processes

Run the App as Stateless Processes

Each process in the application should be Stateless, meaning it’s independent and doesn’t rely on other processes to handle requests.

  • Why? Allows requests to be distributed to any available process without conflicts, enabling scalability.
  • Practical Example: If your app uploads files for processing, any available process can handle the request. If you use PHP Native Sessions (Sticky Sessions), you’ll need a Shared Cache Layer like Redis to remain Stateless.

Stateless processes behind a load balancer serving users

VII. Port Binding

Export Services via Port Binding

The application should be Self-contained and accessible through a single port, without needing an external web server.

  • Why? Makes the app independent and easy to run on the cloud.
  • Practical Example: With Node.js and Express or Python and FastAPI, the app itself acts as the web server. Using PHP with an external server like Apache is less ideal per the 12-Factor App 😊.

Apps exposed as services on their own ports

VIII. Concurrency

Scale Out Using the Process Model

In the 12-Factor App, Processes are the primary unit. As workload increases, the cloud spins up new processes (Horizontal Scaling).

  • Why? Scaling becomes simpler.
  • Practical Example: If user traffic spikes, the cloud automatically launches additional processes to distribute the load.

Web, business and data tiers scaled out behind load balancers

IX. Disposability

Design for Fast Startup and Graceful Shutdown

The application should start quickly and shut down Gracefully when receiving a termination signal.

  • Why? Maintains the stability of backing services and allows resource reuse.
  • Practical Example: When the cloud terminates a process, the app completes current requests and closes connections safely.

Graceful shutdown flow: SIGTERM handler, resource cleanup, SIGKILL fallback

X. Dev/Prod Parity

Keep Development and Production Environments as Similar as Possible

Ensure development and production environments use similar backing services.

  • Why? Differences between environments can cause issues in production that aren’t visible in development.
  • Practical Example: Using SQLite in development and PostgreSQL in production might cause minor issues. Use the same service in both environments if possible.

XI. Logs

Treat Logs as Event Streams

The application shouldn’t manage logs itself. Instead, it writes events to stdout, and the cloud handles log management.

  • Why? Simplifies centralized log management via a Message Queue or Cloud Logging service.
  • Practical Example: The app writes logs to stdout, and the cloud forwards them to a service like AWS CloudWatch.

Logs written to stdout as events and consumed through a message broker

XII. Admin Processes

Run Administrative Tasks as One-Off Processes

Administrative tasks (e.g., database migrations) should be treated as One-off Processes executed by the cloud when needed.

  • Why? Keeps admin tasks organized and easy to execute.
  • Practical Example: Run a database migration as a command in the cloud environment.

Conclusion

The 12-Factor App is designed to simplify Continuous Deployment, reducing the time from development to production from weeks to hours. These principles let engineers build and deploy applications independently, without waiting for Sysadmins or Release Managers.

If your company still uses outdated methods, share this post with them. The world is much easier with the 12-Factor App! 😊

  • #12FactorApp
  • #CloudDevelopment
  • #DevOps
  • #SoftwareEngineering

More articles

All articles