DEV Community

Cover image for Coolify: The Complete Manual Setup Guide (For When the Auto-Install Script Won't Cut It)
Wade Thomas
Wade Thomas

Posted on

Coolify: The Complete Manual Setup Guide (For When the Auto-Install Script Won't Cut It)

#coolify #docker #ansible #selfhosted

Coolify's one-line install script is great — until it isn't. Right now it officially supports Ubuntu 20.04, 22.04, and 24.04 LTS. If you're running anything newer (Ubuntu's already on 26.04 LTS), the script won't work and you're left doing it manually.

This is that manual walkthrough — set up in the order that fits a security-first VPS workflow rather than the order Coolify's own docs use. If you've been following along with the Ansible playbooks from earlier in this series, this picks up right where that left off.

Minimum Hardware Requirements

  • CPU: 2 cores
  • Memory: 2 GB RAM
  • Storage: 30 GB free

Coolify can technically run below this, but it's not recommended.

Prerequisites

Before touching Coolify itself, you'll need:

  • SSH access to your VPS
  • CURL installed
  • Docker Engine installed

If you're reconnecting to a server you've rebuilt or re-provisioned, clear the old fingerprint first:

ssh-keygen -f '/home/your-path/.ssh/known_hosts' -R 'your-vps-ip'
Enter fullscreen mode Exit fullscreen mode

Installing SSH

If you followed the earlier videos in this series, OpenSSH is already installed. If not:

sudo apt update && sudo apt install -y openssh-server
Enter fullscreen mode Exit fullscreen mode

Confirm it's running and check which port it's listening on (you should have already changed this from the default 22 — see the VPS security video):

sudo systemctl status ssh
sudo ss -tulpn | grep ssh
Enter fullscreen mode Exit fullscreen mode

Installing CURL 

sudo apt update && sudo apt install -y curl
curl --version
Enter fullscreen mode Exit fullscreen mode

curl and ca-certificates also get installed as part of the apt-update Ansible playbook below, so this may already be handled.

Running the First Ansible Playbook

Connect Ansible to the VPS:

ANSIBLE_HOST_KEY_CHECKING=FALSE ansible -i ./inventory/hosts vpsDemo -m ping --user root --ask-pass
Enter fullscreen mode Exit fullscreen mode

Then run the update playbook:

ansible-playbook ./playbooks/apt-update.yml --user root -e "ansible_port=22" --ask-pass --ask-become-pass -i ./inventory/hosts
Enter fullscreen mode Exit fullscreen mode

If you haven't set up the Ansible inventory and playbooks from the earlier videos, do that first — this guide assumes they're already in place.

Installing Docker Engine

Remove any conflicting packages first:

sudo apt remove $(dpkg --get-selections docker.io docker-compose docker-compose-v2 docker-doc podman-docker containerd runc | cut -f1)
Enter fullscreen mode Exit fullscreen mode

Add Docker's official GPG key and repo:

sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y
Enter fullscreen mode Exit fullscreen mode

Verify it worked:

sudo systemctl status docker
sudo docker run hello-world
Enter fullscreen mode Exit fullscreen mode

Creating a Non-Root Admin User

Coolify's own docs assume you're using the root account. Since root login is disabled as part of the security hardening earlier in this series, we create a dedicated user with passwordless sudo instead.

Run the second playbook to create that user:

ansible-playbook ./playbooks/basic-secure.yml --user root -e "ansible_port=22" --ask-pass --ask-become-pass -i ./inventory/hosts
Enter fullscreen mode Exit fullscreen mode

Then set up that user's SSH directory:

sudo mkdir -p /home/your-sudo-user/.ssh
sudo touch /home/your-sudo-user/.ssh/authorized_keys
sudo chmod 700 /home/your-sudo-user/.ssh
sudo chmod 600 /home/your-sudo-user/.ssh/authorized_keys
Enter fullscreen mode Exit fullscreen mode

Setting Up Coolify's Directory Structure 

sudo mkdir -p /data/coolify/{source,ssh,applications,databases,backups,services,proxy,webhooks-during-maintenance}
sudo mkdir -p /data/coolify/ssh/{keys,mux}
sudo mkdir -p /data/coolify/proxy/dynamic
Enter fullscreen mode Exit fullscreen mode

Generating and Adding an SSH Key 

sudo ssh-keygen -f /data/coolify/ssh/keys/id.your-sudo-user@host.docker.internal -t ed25519 -N '' -C your-sudo-user@coolify
Enter fullscreen mode Exit fullscreen mode

Add the public key to the authorized_keys file:

cat /data/coolify/ssh/keys/id.your-sudo-user@host.docker.internal.pub | sudo tee -a /home/your-sudo-user/.ssh/authorized_keys
Enter fullscreen mode Exit fullscreen mode

Pulling Coolify's Configuration Files 

sudo curl -fsSL https://cdn.coollabs.io/coolify/docker-compose.yml -o /data/coolify/source/docker-compose.yml
sudo curl -fsSL https://cdn.coollabs.io/coolify/docker-compose.prod.yml -o /data/coolify/source/docker-compose.prod.yml
sudo curl -fsSL https://cdn.coollabs.io/coolify/.env.production -o /data/coolify/source/.env
sudo curl -fsSL https://cdn.coollabs.io/coolify/upgrade.sh -o /data/coolify/source/upgrade.sh
Enter fullscreen mode Exit fullscreen mode

Generating Secure Environment Values

⚠️ Only run these once, on first install. Changing them later can break Coolify. Back them up somewhere safe.

sudo sed -i "s|APP_ID=.*|APP_ID=$(openssl rand -hex 16)|g" /data/coolify/source/.env
sudo sed -i "s|APP_KEY=.*|APP_KEY=base64:$(openssl rand -base64 32)|g" /data/coolify/source/.env
sudo sed -i "s|DB_PASSWORD=.*|DB_PASSWORD=$(openssl rand -base64 32)|g" /data/coolify/source/.env
sudo sed -i "s|REDIS_PASSWORD=.*|REDIS_PASSWORD=$(openssl rand -base64 32)|g" /data/coolify/source/.env
sudo sed -i "s|PUSHER_APP_ID=.*|PUSHER_APP_ID=$(openssl rand -hex 32)|g" /data/coolify/source/.env
sudo sed -i "s|PUSHER_APP_KEY=.*|PUSHER_APP_KEY=$(openssl rand -hex 32)|g" /data/coolify/source/.env
sudo sed -i "s|PUSHER_APP_SECRET=.*|PUSHER_APP_SECRET=$(openssl rand -hex 32)|g" /data/coolify/source/.env
Enter fullscreen mode Exit fullscreen mode

Permissions and Docker Setup

Set correct ownership and permissions:

sudo chown -R 9999:root /data/coolify
sudo find /data/coolify -type d -exec chmod 755 {} \;
sudo find /data/coolify -type f -exec chmod 644 {} \;
sudo chown -R your-sudo-user:your-sudo-user /home/your-sudo-user/.ssh
Enter fullscreen mode Exit fullscreen mode

Create the Docker network Coolify expects:

sudo docker network create --attachable coolify
Enter fullscreen mode Exit fullscreen mode

Add your user to the Docker group:

sudo usermod -aG docker your-sudo-user
Enter fullscreen mode Exit fullscreen mode

Starting Coolify 

sudo docker compose --env-file /data/coolify/source/.env -f /data/coolify/source/docker-compose.yml -f /data/coolify/source/docker-compose.prod.yml up -d --pull always --remove-orphans --force-recreate
Enter fullscreen mode Exit fullscreen mode

Confirm it's running:

sudo docker ps
Enter fullscreen mode Exit fullscreen mode

Then visit http://YOUR-SERVER-IP:8000 in your browser.

Setup your SSL Certificates

Coolify's reverse-proxy Traefik does this under the hood automatically.
In your DNS records add two A records.

A     @     your-vps-ip-address        14400
A     *     your-vps-ip-address        14400
Enter fullscreen mode Exit fullscreen mode

In you Coolify dashboard go to settings in the left side column. In the input box marked URL type your https Subdomain for Coolify there.

https://coolify.yourdomain.com
Enter fullscreen mode Exit fullscreen mode

Traefik will automatically apply a Let's Encrypt certificate to your Coolify subdomain.

Disable port 8000

Disable port 8000 on your VPS. If your hosting provider allows you to configure a firewall from your dashboard, disable it from there. To disable port 8000, simply write rules that allows the ports you want and block everything else.

Wrap-Up

That's a full manual Coolify install on a hardened, non-root VPS — no automated script required. From here, Coolify handles the rest: connecting your Git repos, setting up applications, and managing deployments.

If you hit issues with the automated script on a newer Ubuntu release, this manual path should get you unblocked. Questions or corrections welcome in the comments.

Top comments (0)