Understanding coolify: self-hosted paas architecture, reverse proxy conflicts, and container management

I recently set up and evaluated Coolify as a self-hosted PaaS (Platform as a Service) layer in my own server infrastructure. The main goal was understanding its internal architecture, mapping co-existence scenarios with existing hosting tools (specifically CloudPanel), and testing how its graphical interface manages container lifecycles.

Here are my hands-on technical notes, low-level diagnostics, and infrastructure strategies.

1. What is coolify and how does it work under the hood?#

Coolify is an open-source, self-hosted alternative to services like Heroku, Netlify, and Vercel. It acts as an orchestration controller over the Docker Engine (with experimental Swarm support — Kubernetes is not supported in current v4), removing the need to manually write complex web server configs and custom CI/CD pipelines for every service.

Execution and build mechanics#

• Docker communication: Coolify connects directly to the local Docker socket (/var/run/docker.sock) to provision containers, define overlay networks, and manage storage volumes.
• Build engine (Nixpacks vs Dockerfiles): Rather than requiring a Dockerfile in every project, Coolify defaults to Nixpacks. It inspects repository files (package.json, composer.json, requirements.txt), detects the language runtime, and builds optimized layered Docker images.
• Dynamic routing with Traefik: It includes Traefik as its default edge reverse proxy. Traefik watches the Docker socket, reading container labels in real time. When an application spins up, Traefik detects the routes, handles ACME Let's Encrypt SSL challenges, and updates routing rules without requiring service restarts.

Kernel resource management#

Unlike legacy hosting environments that rely on UID/GID quotas (quotatool), Coolify uses Linux Kernel Control Groups (Cgroups):

• CPU and RAM limits configured in the UI translate to --cpus and --memory flags on the Docker API.
• Stateful services and databases rely on persistent Docker Volumes stored in /var/lib/docker/volumes/, keeping data safe across container redeploys.

2. The challenge: running coolify and CloudPanel on the same host#

In my setup, CloudPanel was already handling production traffic using Nginx and PHP-FPM pools. The primary architectural question was: can Coolify and CloudPanel run side by side on a single server?

The short answer is: technically yes, but it introduces significant operational friction.

Port binding conflicts (Traefik vs Nginx)#

The first collision occurs at the network transport layer:

1. CloudPanel binds Nginx directly to standard ports 80 (HTTP) and 443 (HTTPS).
2. Coolify attempts to bind Traefik to the same 80 and 443 ports by default.
3. When Traefik starts while Nginx is running, the Kernel bind() syscall fails with EADDRINUSE (Address already in use), putting the proxy container into an infinite CrashLoopBackOff.

Resource contention and the Linux OOM killer#

On a shared single host:

• CloudPanel manages local services (Nginx, PHP-FPM, MySQL) directly on the host.
• Heavy build tasks triggered by Coolify (such as compiling Node.js or Rust applications via Nixpacks) cause sharp CPU and memory spikes.
• If physical memory exhausts, the Linux Kernel OOM Killer may terminate critical database or web worker processes.

3. Practical architecture strategies#

To manage co-existence between both systems, I evaluated two practical approaches:

Approach 1: Dedicated instances (recommended)#

Splitting the workloads across isolated servers or VPS instances is the most reliable model:

• Server 1 (CloudPanel): Dedicated to standard PHP applications, websites, and classic Nginx virtual hosts.
• Server 2 (Coolify): Dedicated to microservices, APIs, and containerized workloads deployed via Git.

This separation prevents blast radius expansion: build spikes on Coolify will not degrade site availability on CloudPanel.

Approach 2: Coolify without Traefik + CloudPanel reverse proxy#

If running on a single physical host is mandatory:

1. Set the proxy configuration to None per resource within the Coolify dashboard.
2. Bind Coolify application containers to local internal ports (127.0.0.1:3000, 127.0.0.1:3001).
3. In CloudPanel, configure a Reverse Proxy site directing public domain requests (app.domain.com) to the corresponding internal port.

Important tradeoff: Disabling Traefik transfers SSL certificate issuance and renewals entirely to CloudPanel's Nginx layer.

4. Visual management and UI capabilities#

One of Coolify's greatest advantages is its web dashboard, which streamlines complex terminal routines into visual workflows:

• Git automation and CI/CD: Direct integration with GitHub or GitLab via Webhooks. Every git push triggers builds and atomic zero-downtime redeploys.
• One-click service templates: Instant provisioning of PostgreSQL, MySQL, Redis, and MongoDB with auto-generated credentials, private networks, and persistent volume mounts.
• Real-time log streaming: WebSockets connection streaming container stdout and stderr directly to the browser.
• Interactive browser terminal: Built-in web terminal (docker exec) and dynamic environment variable management (.env) with automatic stack redeployment.

Practical architecture takeaways#

Coolify is an impressive platform for anyone seeking the agility of modern PaaS workflows while retaining full control over their own servers. However, its container-first design and native Traefik integration require thoughtful planning when introduced alongside traditional hosting control panels.

The cleanest strategy is separating workloads across dedicated instances or, if co-hosting on a single machine, carefully planning port bindings and reverse proxy routing to prevent network port conflicts.

See also

DevOps Why Portainer did not see my running container: troubleshooting Docker API and unix socket communication

Servers Does CloudPanel support plugins? Understanding its extensibility and architecture

Servers Debugging Nginx, Varnish, and PHP-FPM in CloudPanel: fixing no input file specified and operation not permitted

This post is licensed under CC BY-NC.