12-Factor App: Modern Practices and the Leapcell Guide
The Twelve-Factor App is a methodology for building modern web applications that are robust, scalable, and maintainable. Originally proposed by Heroku developers, it provides a systematic framework to address the common challenges of application development and operations in the cloud-native era.
By following these 12 factors, developers can create applications optimized for continuous deployment, high portability, and seamless scaling.
Leapcell is designed based on the principles of the 12-Factor App. By adhering to these principles, you can leverage Leapcell’s features to build and deploy applications more efficiently.
This document builds on the classic twelve factors while supplementing them with modern interpretations and best practices for the Leapcell platform.
Modern Interpretations of the 12 Factors and Leapcell Practices
TL;DR
| # | Factor | Summary | Leapcell Practice |
|---|---|---|---|
| I | Codebase for One Service | One repo per app, multiple deploys | One repo per service; clear Git history |
| II | Declare Dependencies | Explicitly declare dependencies | Use manifest files + unify builds with build.sh when needed |
| III | Env as Config | Config is separated from code via env vars | Use .env locally; platform auto-injects env vars |
| IV | Backing Services | Treat external services as pluggable resources | Serverless with /tmp write access; PostgreSQL, Redis, object storage available |
| V | Build, Release, Run | Separate build, release, and run | Auto-trigger build/release from production branch via CI/CD |
| VI | Stateless Processes | Processes should be stateless | Stateless design enables horizontal scaling |
| VII | Port Binding | Export services via port binding | Platform routes external traffic to configured ports |
| VIII | Concurrency | Scale by running multiple processes | Auto-scaling of serverless instances based on traffic |
| IX | Disposability | Fast startup and graceful shutdown | Non-responsive processes receive SIGKILL; apps can handle cleanup |
| X | Dev/prod Parity | Keep dev, staging, and prod as similar as possible | Same codebase; branch + env.local for environment-specific config |
| XI | Logs | Treat logs as event streams | Centralized logging; stream output to stdout |
| XII | Admin Processes | Run admin tasks as one-off processes | Run during build or manually; no pre-start commands |
I. Codebase for One Service
One codebase tracked in version control, many deploys.
An application’s code should be managed in a single repository. Even if multiple environments exist, they must derive from the same codebase.
Leapcell’s deployment model follows this principle. We recommend “one service per repository,” which simplifies project management and ensures clear Git history.
II. Declare Dependencies in a Manifest File
Explicitly declare and isolate dependencies.
Dependencies should be declared in a manifest (package.json, requirements.txt) and managed using proper isolation tools.
Proper dependency management ensures portability. For complex builds, creating a
build.shscript is recommended to unify build steps.
III. Env as Config
Store configuration in the environment.
Settings (DB URLs, API keys, etc.) should be separated from code and injected via environment variables.
Use
.envlocally. On Leapcell, predefined environment variables are automatically injected into the runtime, making the transition from local to production smooth.
IV. Backing Services
Treat backing services as attached resources.
Services accessed over the network should be connected via URLs and credentials.
Leapcell’s serverless runtime provides a read-only filesystem except for
/tmp. Externalizing state allows for fast, dynamic scheduling. PostgreSQL, Redis, and object storage are also provided.
V. Build, Release, Run
Strictly separate build, release, and run stages.
Releases should be immutable and easily rolled back. This process should be automated via CI/CD.
On Leapcell, committing to the production branch automatically triggers build and release, deploying the latest code to production.
VI. Stateless Processes
Execute the app as stateless processes.
Any data that needs persistence must be stored in backing services.
Stateless design makes horizontal scaling easy. Leapcell’s serverless model fully supports this.
VII. Port Binding
Export services via port binding.
The platform routes external traffic to the configured port.
VIII. Concurrency
Scale out via process concurrency.
Serverless instances automatically scale based on incoming traffic.
IX. Disposability
Maximize robustness with fast startup and graceful shutdown.
Non-responsive processes are sent SIGKILL. Applications can handle necessary cleanup before termination.
X. Dev/prod Parity
Keep development, staging, and production as similar as possible.
Use the same codebase, and configure environment-specific settings via branch +
env.local.
XI. Logs
Treat logs as event streams.
All logs are centrally managed and output to stdout for analysis.
XII. Admin Processes
Run admin/management tasks as one-off processes.
Leapcell does not provide pre-start commands. These tasks can be run manually or during the build process.