Implementing 12-Factor App Methodology with DeployHQ

The 12-Factor App methodology has become the gold standard for building modern, scalable, and maintainable web applications. Originally published by Heroku engineers, these twelve principles provide a battle-tested framework for creating applications that are portable, resilient, and ready for continuous deployment.

If you're building or maintaining web applications, understanding these factors can transform how you think about deployment. In this guide, we'll walk through each of the 12 factors and show how DeployHQ's deployment platform helps you implement them — from codebase management to admin processes. For a conceptual overview, see our companion article on what the 12-Factor App methodology is.

flowchart TD
    A[12-Factor App with DeployHQ] --> B[Codebase]
    A --> C[Dependencies]
    A --> D[Config]
    A --> E[Backing Services]
    A --> F[Build/Release/Run]
    A --> G[Processes]
    A --> H[Port Binding]
    A --> I[Concurrency]
    A --> J[Disposability]
    A --> K[Dev/Prod Parity]
    A --> L[Logs]
    A --> M[Admin Processes]

What is the 12-Factor App Methodology?

The 12-Factor App is a methodology for building software-as-a-service applications that emphasizes:

• Portability across execution environments
• Scalability without significant architectural changes
• Continuous deployment for maximum development agility
• Minimal divergence between development and production environments

Let's dive into how DeployHQ supports each factor.

I. Codebase: One Codebase Tracked in Revision Control

The Factor: One codebase tracked in revision control, many deploys.

DeployHQ Implementation:

DeployHQ excels at this fundamental requirement by supporting multiple version control systems including Git, SVN, and Mercurial. The platform integrates seamlessly with popular repositories like GitHub, GitLab, and Bitbucket.

Key Features:

• Multi-repository support: Connect projects from GitHub, GitLab, Bitbucket, or self-hosted repositories
• Branch-specific deployments: Configure different servers to deploy from specific branches (development, staging, production)
• Single source of truth: One codebase can be deployed to multiple environments with different configurations

Best Practice with DeployHQ: Set up separate server configurations for each environment, all pointing to the same repository but potentially different branches:

• Development server: develop branch
• Staging server: release branch
• Production server: main branch

II. Dependencies: Explicitly Declare and Isolate Dependencies

The Factor: Explicitly declare and isolate dependencies.

DeployHQ Implementation:

DeployHQ's build pipeline system allows you to manage dependencies consistently across all deployments through custom build environments and automated dependency installation.

Key Features:

• Custom build environments: Configure specific versions of Ruby, PHP, Node.js, Java, and other tools
• Build pipeline commands: Automate dependency installation with commands like npm install, composer install, or bundle install
• Consistent environments: Ensure the same dependency versions across all deployments

Example Build Pipeline Configuration:

bundle install --deployment --without development test
npm ci --production
npm run build:production

III. Config: Store Configuration in the Environment

The Factor: Store config in the environment.

DeployHQ Implementation:

While DeployHQ doesn't currently offer built-in environment variable management per server, it provides robust configuration management through config files and deployment variables.

Key Features:

• Config files: Store sensitive configuration separate from your codebase
• Environment-specific variables: Use variables like %environment%, %branch%, and %deployment_url%
• Secure configuration management: Keep sensitive data out of version control

Implementation Strategy: Create environment-specific config files in DeployHQ:

production:
  adapter: postgresql
  host: %database_host%
  database: myapp_%environment%
  username: %database_user%
  password: %database_password%

Pro Tip: Use DeployHQ's config file feature combined with server-specific environment settings to maintain configuration separation while leveraging the platform's deployment capabilities. If you only need to push configuration changes without redeploying your entire codebase, DeployHQ's deploy only configuration files feature lets you update config files independently. For more on keeping configurations secure, see our guide on protecting your deployment environments.

IV. Backing Services: Treat Backing Services as Attached Resources

The Factor: Treat backing services as attached resources.

DeployHQ Implementation:

DeployHQ supports this factor through its flexible configuration system and integration capabilities, allowing you to easily switch between different backing services across environments.

Key Features:

• Environment-specific configurations: Different database, cache, or API configurations per environment
• SSH command integration: Run commands to configure or migrate backing services during deployment
• Config file flexibility: Store different service endpoints for each environment

Example Implementation:

rails db:migrate RAILS_ENV=%environment%
curl -f http://%service_endpoint%/health || exit 1

V. Build, Release, Run: Strictly Separate Build and Run Stages

The Factor: Strictly separate build, release, and run stages.

DeployHQ Implementation:

DeployHQ's deployment pipeline naturally enforces this separation with distinct build and deployment phases.

The Three Stages in DeployHQ:

1. Build Stage:

   • Code compilation through build pipelines
   • Asset processing and minification
   • Dependency installation
   • Test execution

2. Release Stage:

   • Combines build artifacts with configuration
   • Creates deployment-ready packages
   • Version tagging and tracking

3. Run Stage:

   • Atomic deployments ensure clean releases
   • Zero-downtime deployments
   • Automatic rollback capabilities

Build Pipeline Example:

npm run test
npm run build:production
composer install --no-dev --optimize-autoloader

VI. Processes: Execute the App as One or More Stateless Processes

The Factor: Execute the app as one or more stateless processes.

DeployHQ Implementation:

DeployHQ supports stateless application deployment through its atomic deployment process and server configuration options.

Key Features:

• Atomic deployments: Ensure clean process restarts
• Multiple server support: Deploy to multiple application servers
• Process management: Use SSH commands to restart application processes
• Session storage: Configure external session storage through config files

Implementation Example:

sudo systemctl restart nginx
sudo systemctl restart app-worker
sudo php-fpm reload
php artisan cache:clear

VII. Port Binding: Export Services via Port Binding

The Factor: Export services via port binding.

DeployHQ Implementation:

DeployHQ supports port binding configuration through its flexible server setup and configuration management.

Key Features:

• Server-specific configurations: Configure different ports for different environments
• Load balancer support: Deploy to multiple servers behind load balancers
• Environment variables: Use port configuration in config files

Configuration Example:

server {
    listen %app_port%;
    server_name %server_name%;

    location / {
        proxy_pass http://localhost:%internal_app_port%;
    }
}

VIII. Concurrency: Scale Out via the Process Model

The Factor: Scale out via the process model.

DeployHQ Implementation:

DeployHQ facilitates horizontal scaling through its multi-server deployment capabilities and process management features.

Key Features:

• Server groups: Deploy to multiple servers simultaneously
• Load balancer integration: Support for various hosting platforms
• Process management: Configure different process types through SSH commands
• Environment-specific scaling: Different server configurations per environment

Scaling Strategy:

sudo systemctl start app-web@{1..4}
sudo systemctl start app-worker@{1..2}
sudo systemctl start app-scheduler

IX. Disposability: Maximize Robustness with Fast Startup and Graceful Shutdown

The Factor: Maximize robustness with fast startup and graceful shutdown.

DeployHQ Implementation:

DeployHQ's atomic deployment system inherently supports disposability by ensuring clean, predictable deployments.

Key Features:

• Atomic deployments: All-or-nothing deployment approach
• Zero-downtime deployments: Graceful process switching
• Rollback capabilities: Quick recovery from failed deployments
• Health checks: Verify application health before completion

Implementation:

sudo systemctl reload nginx
pkill -TERM -f "app-worker"
curl -f http://localhost/health || exit 1

X. Dev/Prod Parity: Keep Development, Staging, and Production as Similar as Possible

The Factor: Keep development, staging, and production as similar as possible.

DeployHQ Implementation:

DeployHQ excels at maintaining environment parity through consistent deployment processes and configuration management. For a deep dive, see our guide on keeping environments in sync.

Key Features:

• Consistent build process: Same build pipeline across all environments
• Environment-specific configurations: Maintain same structure, different values
• Branch-based deployments: Similar code paths with environment-appropriate branches
• Identical deployment process: Same steps across all environments

Best Practices:

• Use the same build pipeline commands across environments
• Maintain similar server configurations with environment-specific values
• Deploy frequently to reduce drift between environments
• Use feature flags for environment-specific functionality

XI. Logs: Treat Logs as Event Streams

The Factor: Treat logs as event streams.

DeployHQ Implementation:

While DeployHQ doesn't provide log aggregation directly, it supports log management through deployment integration and monitoring setup.

Key Features:

• Deployment logging: Comprehensive deployment logs and history
• SSH command integration: Set up log forwarding during deployment
• Integration support: Connect with log management services
• Build pipeline logging: Detailed build and deployment process logs

Log Management Setup:

echo "*.* @@logs.example.com:514" >> /etc/rsyslog.conf
systemctl restart rsyslog
logrotate -f /etc/logrotate.conf

XII. Admin Processes: Run Admin/Management Tasks as One-off Processes

The Factor: Run admin/management tasks as one-off processes.

DeployHQ Implementation:

DeployHQ supports admin processes through its SSH command system and flexible deployment configuration. You can also use the DeployHQ API to trigger administrative tasks programmatically.

Key Features:

• SSH commands: Run one-off administrative tasks during deployment
• Manual deployment triggers: Execute admin processes on-demand
• Environment-specific commands: Different admin tasks per environment
• Safe execution: Run admin processes in the same environment as the application

Admin Task Examples:

rails db:migrate RAILS_ENV=%environment%
php artisan cache:warm
python manage.py cleanup_old_data --days=30
php artisan scout:import "App\\Models\\Product"

Bringing It All Together

Here's how a complete 12-factor application deployment looks in DeployHQ:

1. Project Setup

• Connect your Git repository (Factor I: Codebase)
• Configure build pipeline for dependency management (Factor II: Dependencies)

2. Environment Configuration

• Set up config files for each environment (Factor III: Config)
• Configure backing service endpoints (Factor IV: Backing Services)

3. Deployment Pipeline

• Build pipeline handles compilation and testing (Factor V: Build/Release/Run)
• Atomic deployments ensure clean releases (Factor VI: Processes)

4. Server Configuration

• Configure port bindings and server settings (Factor VII: Port Binding)
• Set up server groups for scaling (Factor VIII: Concurrency)

5. Deployment Process

• Zero-downtime deployments support disposability (Factor IX: Disposability)
• Consistent process across environments (Factor X: Dev/Prod Parity)

6. Operations

• Comprehensive deployment logging and monitoring (Factor XI: Logs)
• SSH commands for admin processes (Factor XII: Admin Processes)

FAQ

Do I need to implement all 12 factors at once? No. The factors are independent principles. Start with the ones that address your biggest pain points — typically Factor III (Config), Factor V (Build/Release/Run), and Factor X (Dev/Prod Parity) — and adopt the rest incrementally.

Does DeployHQ replace my CI system? DeployHQ focuses on deployment, not full CI. It works alongside your existing CI tools (GitHub Actions, GitLab CI, etc.) to handle the deployment stage. You can use DeployHQ's build pipelines for build-time tasks like dependency installation and asset compilation.

How does DeployHQ handle database migrations? Use pre- or post-deployment SSH commands to run migrations as part of your deployment process. For details, see our guide on database deployments with DeployHQ.

Can I use this approach with Docker? Yes. DeployHQ can deploy to any server accessible via SSH. For container-based workflows, use SSH commands to trigger Docker builds and orchestration. See our guide on deploying to AWS ECS/EKS with DeployHQ.

Conclusion

DeployHQ provides a robust platform for implementing 12-Factor App methodology, offering the tools and flexibility needed to build scalable, maintainable applications. While some factors require additional tooling (like dedicated environment variable management or log aggregation services), DeployHQ's core features align well with 12-factor principles.

The platform's strength lies in its simplicity and reliability, making it easier for teams to adopt 12-factor practices without overwhelming complexity. By leveraging DeployHQ's build pipelines, atomic deployments, configuration management, and multi-environment support, you can create a deployment process that embodies the best practices of modern application development.

Ready to implement 12-factor principles in your applications? Sign up for DeployHQ and start deploying the right way. For questions, reach out to our support team at support@deployhq.com or find us on Twitter.