Coolify: Self-Hosted PaaS Technical Reference

Core Architecture

Technology Stack:

• Docker containers for application isolation
• Traefik reverse proxy for routing and SSL
• Nixpacks for automatic application detection (Heroku buildpack alternative)
• Let's Encrypt for automated SSL certificate management
• Apache 2.0 license (commercial use permitted)

Installation Requirements:

• Ubuntu 22.04+ (other distros supported but Ubuntu has fewest issues)
• 2GB RAM minimum (4GB recommended to prevent OOMKill events)
• Ports 80, 443, 8000 must be open
• Clean server (existing Docker installations may cause conflicts)
• Single command installation: curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

Production Configuration

Deployment Capabilities:

• Supports any Docker-compatible application
• Git integration: GitHub, GitLab, Bitbucket
• Automatic webhook setup for CI/CD
• Zero-downtime rolling updates
• PR preview environments with unique URLs
• Built-in databases: PostgreSQL, MySQL, MongoDB, Redis, ClickHouse
• Automated S3 backups for databases
• 150+ one-click service templates

Resource Requirements:

• Time investment: One weekend for initial migration from Heroku
• Learning curve: Moderate (requires Linux system administration knowledge)
• Expertise needed: Basic to intermediate Linux/Docker knowledge
• Scaling model: Vertical scaling (upgrade server) or Docker Swarm clustering

Critical Warnings

Single Points of Failure:

• Server death = complete service outage (no automatic failover)
• Requires manual intervention for scaling during traffic spikes
• Self-managed infrastructure responsibility (security, updates, monitoring)

Common Failure Modes:

• Memory exhaustion with <4GB RAM causes container crashes
• Webhook timeouts during deployment (community-reported issue)
• Disk space exhaustion causes service failures
• SSL certificate renewal failures if DNS misconfigured

Production Limitations:

• No automatic horizontal scaling
• No multi-region failover capabilities
• Kubernetes support delayed (announced but not delivered)
• Requires SSH access for troubleshooting

Cost Analysis

Verified Savings (18-month production data):

• Previous Heroku cost: $97/month
• Current Coolify + Hetzner VPS: $12/month
• Annual savings: $1,020
• Total 18-month savings: $2,400

Pricing Models:

• Self-hosted: VPS cost only ($5-20/month)
• Coolify Cloud: $5/month + $3 per server
• Compare to Heroku: $7+ per dyno + database add-ons ($200/month for 10GB PostgreSQL)

Decision Support Information

Choose Coolify When:

• Comfortable with Linux system administration
• Need cost reduction over managed services
• Require full infrastructure control
• Have <100k users (proven scale limit)
• Acceptable with occasional manual intervention

Avoid Coolify When:

• Need 99.99% uptime guarantees
• Require automatic horizontal scaling
• Team lacks Linux expertise
• Need enterprise-grade support contracts

Trade-offs Assessment:

• "Worth it despite single server limitations" for cost-conscious developers
• Community support quality exceeds Heroku (Discord responses <20 minutes)
• Learning investment pays off through significant cost savings
• Infrastructure control enables customization impossible with managed services

Migration Process

Heroku to Coolify Steps:

1. Export Heroku database
2. Create equivalent services in Coolify
3. Import database
4. Configure environment variables (copy-paste compatible)
5. Update DNS records
6. Total time: One weekend for 4 applications

Breaking Changes to Expect:

• No automatic scaling (manual server provisioning required)
• Direct server access needed for advanced debugging
• SSL certificate management through Coolify interface only

Support and Community

Community Quality Indicators:

• 44.6k GitHub stars
• 17k+ Discord members with active technical support
• Average response time: <20 minutes for technical questions
• Regular releases every 2-3 weeks
• Active contributor base with good documentation

Known Workarounds:

• Webhook timeout issues: Increase timeout values in configuration
• Memory pressure: Monitor container usage, upgrade to 4GB+ RAM
• SSL renewal failures: Verify DNS propagation before deployment
• Deployment failures: Check build logs, usually dependency conflicts

Performance Thresholds

Proven Scale Limits:

• Successfully tested with <100k users
• Memory usage scales linearly with concurrent connections
• Database performance depends on underlying VPS specifications
• No reported UI performance issues up to documented scale

Resource Scaling Indicators:

• 2GB RAM: Development/testing only
• 4GB RAM: Small production applications
• 8GB+ RAM: Medium production workloads with databases
• Horizontal scaling requires Docker Swarm setup (advanced configuration)