How to Setup Coolify on a Hetzner VPS
A step-by-step guide to installing Coolify on a Hetzner VPS and setting up production-ready deployments with GitHub Actions and Docker.
Prerequisites
Before starting, you'll need a fresh Ubuntu server and a domain pointing to it. I recommend Ubuntu 22.04 or 24.04 for compatibility. The recommended server specs are 2 CPU cores, 4GB RAM, and 40GB storage, which aligns perfectly with Hetzner's CX23 VPS.
You'll also need root access to the server, ports 80, 443, and 8000 open for HTTP, HTTPS, and the Coolify dashboard respectively. Make sure Docker is not already configured with IPv6—this is a common source of proxy errors during installation.
Step 1: Disable IPv6 in Docker
This is a critical step that prevents the most common Coolify installation issue. By default, Docker can automatically create networks with IPv6 enabled, which causes Coolify's proxy (Traefik) to fail with cryptic errors like ParseAddr("fdxx:xxxx::1/64"). The proxy expects a pure IPv4 network configuration, and when it encounters IPv6 addresses, it cannot properly parse the network routes. This is a well-documented issue in the Coolify community.
Before installing Coolify, configure Docker to disable IPv6 support. Create or edit the Docker daemon configuration file at /etc/docker/daemon.json and add {"ipv6": false}. This ensures that all Docker networks, including the one Coolify creates, will use IPv4 only.
After saving the file, restart Docker with sudo systemctl restart docker and verify it's running with sudo systemctl status docker. You should see active (running) in the output.
Step 2: Install Coolify
Coolify provides an official installation script that handles the entire setup process. Run the following command on your server:
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash
This installs the core Coolify containers: coolify, coolify-db, coolify-redis, and coolify-realtime. The installation typically takes a few minutes depending on your server's network speed.
Once complete, verify the installation by running docker ps. You should see all four Coolify containers running. You can also inspect the Docker network with docker network inspect coolify and confirm that EnableIPv6 is set to false.
Step 3: Access the Dashboard
Open your browser and navigate to http://YOUR_SERVER_IP:8000. You'll be prompted to complete the initial setup, which includes creating a root user, setting up your first team, and configuring the server connection.
During this process, add your server by selecting Localhost as the server type. Coolify will automatically connect to the Docker daemon running on the same machine.
Step 4: Configure DNS and Domain
Before you can deploy applications with SSL, configure your DNS records. In your DNS provider (Cloudflare, Namecheap, etc.), add the following records:
A wildcard record (*) pointing to your server IP, a root record (@) pointing to your server IP, a subdomain for Coolify itself (e.g., coolify) pointing to your server IP, and optionally a CNAME for www pointing to your domain.
Back in Coolify, navigate to Servers → localhost → Configuration → General and set the Wildcard Domain to https://*.your-domain.com. This allows Coolify to automatically route subdomains to your applications.
Step 5: Start the Proxy
Coolify uses a reverse proxy (Traefik) to route traffic to your applications. Navigate to Servers → localhost → Proxy and click Start Proxy. Wait until the status shows Proxy Running.
Verify the proxy is running by checking docker ps—you should now see a coolify-proxy container in addition to the core Coolify containers.
Step 6: Configure Coolify Dashboard Domain
For security and convenience, set up a proper domain for the Coolify dashboard instead of accessing it via IP and port. Navigate to Settings → Configuration → General and set the URL to coolify.your-domain.com.
Coolify will automatically configure SSL via Let's Encrypt. After a few moments, you'll be able to access your dashboard at https://coolify.your-domain.com instead of using the IP and port.
Step 7: Deploy Your First Application
Create a project by navigating to Projects → Add+. Give it a name and description. Then, add a resource by selecting Docker Image and specifying your image name (e.g., ghcr.io/your-username/your-image) and tag (usually latest).
In the application configuration, set the Domains field to your desired domain(s), such as https://your-domain.com,https://www.your-domain.com. You can configure redirect behavior (e.g., non-www to www or vice versa) in the same section.
Under Network → Ports Exposes, specify which port your application listens on (e.g., 3000 for most Node.js apps). Coolify will route traffic from ports 80 and 443 to this internal port.
Click Save, then click Deploy. Coolify will pull the Docker image, start the container, attach it to the proxy, and configure SSL automatically. Your application will be live at your domain within a few minutes.
Step 8: Set Up CI/CD with GitHub Actions
For automated deployments, configure a GitHub Actions workflow that builds your Docker image, pushes it to a registry (like GitHub Container Registry), and triggers a Coolify deployment.
First, configure your Coolify application to always pull the latest image. In your application settings, enable Always pull latest image. Then, set up a healthcheck so Coolify knows when your application is ready. Under Healthcheck, configure the method (GET), scheme (http), host (localhost), port (3000), and path (e.g., /api/health).
In Coolify, navigate to your application's Configuration → Webhooks and copy the Deploy Webhook URL. Also, go to Keys & Tokens → API Tokens and create a new token with deploy permissions.
In your GitHub repository, go to Settings → Secrets and variables → Actions and add two secrets: COOLIFY_TOKEN (the API token) and COOLIFY_WEBHOOK (the webhook URL).
Create a GitHub Actions workflow file at .github/workflows/deploy.yml that builds your Docker image, pushes it to GHCR, and triggers the Coolify webhook. The workflow should authenticate to GHCR using secrets.GITHUB_TOKEN, build and tag the image with both latest and the commit SHA, and finally call the Coolify webhook to trigger a deployment.
With this setup, every push to your main branch will automatically build, push, and deploy your application to Coolify.
Common Issues and Solutions
If the proxy fails to start with an IPv6 error, stop all containers with docker stop $(docker ps -aq), remove the network with docker network rm coolify, recreate it with docker network create coolify, and restart the containers from the Coolify dashboard.
If health checks are failing, verify that your application is listening on 0.0.0.0 and not just localhost, that the health endpoint exists and returns a successful status code, and that your Docker image includes curl or wget for the healthcheck command.
If the image isn't pulling from the registry, ensure the image is public or that Coolify has credentials configured, verify that "Always pull latest image" is enabled, and confirm the image tag exists in your registry.
Conclusion
Coolify transforms a basic VPS into a powerful deployment platform with minimal effort. Once configured, you have a production-ready environment with automatic SSL, Docker-based deployments, and webhook-driven CI/CD. The setup process takes about an hour, but the result is infrastructure you fully control and understand.
This setup is ideal for personal projects, side projects, or small production applications. You get the simplicity of managed platforms like Vercel with the control and cost efficiency of self-hosting. For developers looking to build DevOps skills while deploying real applications, Coolify is an excellent choice.