Add tutorial: Installing Coolify - A Self-Hosted PaaS on Hetzner Cloud

tutorials/install-coolify-self-hosted-paas-on-hetzner/01.en.md

@@ -0,0 +1,287 @@
+---
+SPDX-License-Identifier: MIT
+path: "/tutorials/install-coolify-self-hosted-paas-on-hetzner"
+slug: "install-coolify-self-hosted-paas-on-hetzner"
+date: "2026-05-06"
+title: "Installing Coolify - A Self-Hosted PaaS on Hetzner Cloud"
+short_description: "Learn how to install Coolify, an open-source self-hosted PaaS alternative to Heroku and Netlify, on a Hetzner Cloud server running Ubuntu 24.04, and deploy your first application with automatic HTTPS."
+tags: ["Coolify", "Docker", "Ubuntu", "PaaS", "Deployment", "Linux"]
+author: "Riyaz"
+author_link: "https://github.com/RiyazClevMind"
+author_img: "https://avatars.githubusercontent.com/u/182978028?v=4"
+author_description: ""
+language: "en"
+available_languages: ["en"]
+header_img: "header-x"
+cta: "cloud"
+---
+
+## Introduction
+
+Coolify is an open-source, self-hosted Platform-as-a-Service (PaaS) that gives you a Heroku-style deployment experience on your own infrastructure. With Coolify, you can deploy applications directly from a Git repository, provision databases, manage environment variables, and get automatic HTTPS — all from a single web dashboard running on your own Hetzner Cloud server.
+
+Unlike managed PaaS platforms that charge per application or dyno, Coolify lets you deploy as many applications as your server resources allow, at no additional cost beyond the server itself. All configuration is stored on your own server, so you are never locked in to Coolify — if you stop using it, your running Docker containers and databases remain intact.
+
+In this tutorial, you will install Coolify on a Hetzner Cloud server running Ubuntu 24.04, configure a custom domain with HTTPS for the Coolify dashboard, open the required firewall ports, and deploy a sample application to verify the full workflow.
+
+**Prerequisites**
+
+* A Hetzner Cloud server running **Ubuntu 24.04** with at least 2 vCPUs and 4 GB RAM. The **CX22** instance type meets these requirements comfortably. It is recommended to use a fresh server with no existing software installed to avoid conflicts with Coolify's Docker environment.
+* A **domain name** you control, with the ability to add DNS records. Two subdomains are needed — one for the Coolify dashboard (e.g. `coolify.<example.com>`) and one for your first deployed application (e.g. `app.<example.com>`).
+* SSH access to the server as `root` or as a user with `sudo` privileges.
+* Basic familiarity with the Linux command line.
+
+**Example terminology**
+
+| Placeholder | Example value |
+|---|---|
+| Username | `holu` |
+| Coolify dashboard domain | `coolify.<example.com>` |
+| Application domain | `app.<example.com>` |
+| Server IP | `<10.0.0.1>` |
+
+## Step 1 - Prepare the Server
+
+Connect to your server as `root` or as `holu` with sudo access:
+
+```bash
+ssh holu@<10.0.0.1>
+```
+
+Update the system and install the prerequisite packages Coolify's installer requires:
+
+```bash
+sudo apt update && sudo apt upgrade -y
+sudo apt install -y curl wget git
+```
+
+Coolify's installer automatically installs Docker if it is not already present. However, if Docker was previously installed via Ubuntu's `snap` package manager, it must be removed first, as Coolify does not support Docker installed through snap:
+
+```bash
+sudo snap remove docker 2>/dev/null || true
+```
+
+If Docker is already installed via `apt` or the official Docker repository, you can leave it in place — the Coolify installer will detect it and skip reinstallation.
+
+## Step 2 - Open Required Firewall Ports
+
+Coolify requires the following ports to be reachable from the internet:
+
+| Port | Purpose |
+|---|---|
+| 22 | SSH access |
+| 80 | HTTP (used for Let's Encrypt domain verification and HTTP-to-HTTPS redirects) |
+| 443 | HTTPS for deployed applications and the Coolify dashboard |
+| 8000 | Coolify dashboard (HTTP, used before a domain is configured) |
+| 6001 | Coolify WebSocket server (real-time deployment logs) |
+| 6002 | Coolify terminal access |
+
+Configure UFW to allow these ports:
+
+```bash
+sudo ufw allow OpenSSH
+sudo ufw allow 80/tcp
+sudo ufw allow 443/tcp
+sudo ufw allow 8000/tcp
+sudo ufw allow 6001/tcp
+sudo ufw allow 6002/tcp
+sudo ufw enable
+```
+
+> **Note for Hetzner Cloud users:** Hetzner Cloud does not apply network-level firewall rules by default, so UFW is the primary firewall. If you have configured a Hetzner Cloud Firewall in the Cloud Console, make sure the same ports are also allowed there — both firewalls must permit the traffic.
+
+Verify the rules are active:
+
+```bash
+sudo ufw status
+```
+
+## Step 3 - Install Coolify
+
+Run the official Coolify installation script. This script installs Docker (if not already present), pulls the Coolify Docker images, generates a random encryption key, and starts all required containers:
+
+```bash
+curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash
+```
+
+The installation takes between 2 and 10 minutes depending on your server's network speed. You will see step-by-step progress output. A successful installation ends with output similar to:
+
+```
+============================================================
+[2026-05-06 10:00:00] Installation Complete
+============================================================
+Coolify is now accessible at: http://<10.0.0.1>:8000
+```
+
+If the script hangs on **"Waiting for Docker to start"**, Docker may have failed to start due to a kernel mismatch. Reboot the server and run the script again:
+
+```bash
+sudo reboot
+```
+
+After the reboot, re-run the installation script to resume.
+
+Verify all Coolify containers are running after installation:
+
+```bash
+sudo docker ps --format "table {{.Names}}\t{{.Status}}"
+```
+
+You should see the following containers all in a running state:
+
+```
+NAMES               STATUS
+coolify             Up X minutes
+coolify-db          Up X minutes
+coolify-redis       Up X minutes
+coolify-realtime    Up X minutes
+coolify-proxy       Up X minutes
+```
+
+## Step 4 - Configure a DNS Record for the Dashboard
+
+Before opening Coolify in the browser, add a DNS A record pointing your dashboard subdomain to your server's IP address. Log in to your domain registrar or DNS provider and add:
+
+```
+coolify.<example.com>    A    <10.0.0.1>
+```
+
+DNS propagation can take a few minutes to a few hours. You can verify the record has propagated with:
+
+```bash
+dig +short coolify.<example.com>
+```
+
+The output should show your server's IP address. Once it resolves correctly, proceed to the next step.
+
+## Step 5 - Initial Setup and Admin Account
+
+Open your browser and navigate to the Coolify dashboard on port 8000:
+
+```
+http://<10.0.0.1>:8000
+```
+
+You will see the Coolify registration page. The first account created automatically becomes the administrator.
+
+Fill in your name, email address, and a strong password, then click **Register**. You will be taken to the onboarding wizard.
+
+### Step 5.1 - Onboarding Wizard
+
+The onboarding wizard walks you through three steps:
+
+**Step 1 — Select a server:** Choose **Localhost** to use the same Hetzner server that Coolify is running on. This is the recommended choice for getting started — you can add additional remote servers later via SSH.
+
+**Step 2 — Configure SSH:** Coolify generates an SSH key during installation. Select **Use Existing Key**. Coolify will test the SSH connection to localhost and show a green checkmark if it succeeds.
+
+**Step 3 — Create a project:** Click **Create "My First Project"**. Projects group related applications and databases together.
+
+Click **Finish** to complete the wizard and reach the main dashboard.
+
+### Step 5.2 - Configure the Dashboard Domain
+
+To access Coolify via HTTPS on your custom subdomain instead of the IP and port 8000, configure the domain in the Coolify settings.
+
+In the Coolify dashboard, go to **Settings** (the gear icon in the left sidebar) → **General**. Find the **Instance's Domain** field and enter:
+
+```
+https://coolify.<example.com>
+```
+
+Click **Save**. Coolify will instruct its built-in Traefik reverse proxy to obtain a Let's Encrypt certificate for your subdomain and begin serving the dashboard over HTTPS. This takes about 30–60 seconds.
+
+Navigate to:
+
+```
+https://coolify.<example.com>
+```
+
+You should see the Coolify login page with a valid SSL certificate. Port 8000 will continue to work as a fallback, but HTTPS on your custom domain is now the primary access point.
+
+> **Important:** Back up the file `/data/coolify/source/.env` to a safe location. This file contains your database passwords, encryption key, and other sensitive configuration. If this file is lost, you cannot recover encrypted secrets stored in Coolify.
+
+## Step 6 - Deploy Your First Application
+
+With Coolify running, deploy a sample application to verify the full workflow end to end.
+
+In the Coolify dashboard:
+
+1. Click **Projects** in the left sidebar → select **My First Project**
+2. Click **+ New Resource**
+3. Select **Public Repository**
+4. In the **Git Repository URL** field, enter a public repository. For this example, use the official Coolify test application:
+   ```
+   https://github.com/coollabsio/coolify-examples
+   ```
+5. Select the branch `main` and choose the `nodejs-fastify` example from the subdirectory list
+6. Click **Continue**
+
+On the application configuration page:
+
+- Set the **Domain** to `app.<example.com>`
+- Leave the **Port** as detected (typically `3000`)
+- Click **Save**
+
+Add a DNS A record for your application domain:
+
+```
+app.<example.com>    A    <10.0.0.1>
+```
+
+Then click **Deploy** in the Coolify dashboard. You will see real-time build logs stream in the **Deployments** tab as Coolify clones the repository, builds the Docker image, and starts the container.
+
+Once the deployment shows a green **Running** status, open your browser and navigate to:
+
+```
+https://app.<example.com>
+```
+
+You should see the sample application running with a valid HTTPS certificate, provisioned automatically by Coolify via Let's Encrypt.
+
+## Step 7 - Configure Notifications (Optional)
+
+Coolify can send notifications when a deployment succeeds or fails. In the dashboard, go to **Settings** → **Notifications** and enable at least one channel — options include Email, Discord, Slack, and Telegram. Configuring this is recommended for production use so you are alerted immediately if a deployment fails.
+
+## Conclusion
+
+You now have a fully operational self-hosted PaaS running on your Hetzner Cloud server. Your setup includes:
+
+- **Coolify** installed and managed via Docker Compose
+- The Coolify dashboard accessible via **HTTPS** on a custom subdomain with an automatically renewed Let's Encrypt certificate
+- A **UFW firewall** with only the required ports open
+- A sample application successfully deployed with automatic HTTPS
+
+From here, you can connect your own GitHub, GitLab, or Gitea repositories to Coolify for automatic deployments on every push, provision managed databases (PostgreSQL, MySQL, Redis, MongoDB) with a single click, and add additional Hetzner Cloud servers to your Coolify instance via SSH to distribute your workload across multiple machines.
+
+For upgrades, Coolify checks for new versions automatically and displays an **Update** button in the dashboard when a new release is available.
+
+##### License: MIT
+
+<!--
+
+Contributor's Certificate of Origin
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I have
+    the right to submit it under the license indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best of my
+    knowledge, is covered under an appropriate license and I have the
+    right under that license to submit that work with modifications,
+    whether created in whole or in part by me, under the same license
+    (unless I am permitted to submit under a different license), as
+    indicated in the file; or
+
+(c) The contribution was provided directly to me by some other person
+    who certified (a), (b) or (c) and I have not modified it.
+
+(d) I understand and agree that this project and the contribution are
+    public and that a record of the contribution (including all personal
+    information I submit with it, including my sign-off) is maintained
+    indefinitely and may be redistributed consistent with this project
+    or the license(s) involved.
+
+Signed-off-by: Riyaz riyaz@clevmind.com
+
+-->