When the Auto-Install Script Fails

Coolify's one-line install script is a convenience, but it officially supports only Ubuntu 20.04, 22.04, and 24.04 LTS. As Ubuntu advances to versions like 26.04 LTS, this script breaks. This guide details a manual setup process, prioritizing security and following a workflow suited for VPS environments, distinct from Coolify's own documentation order. This guide assumes you have basic familiarity with server administration and potentially have used Ansible playbooks in prior setup stages.

Minimum Hardware Requirements

While Coolify can technically operate on less, the recommended minimum specifications for stable operation are:

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

Exceeding these minimums is advisable for smoother performance, especially if you plan to host multiple applications or services.

Prerequisites for Manual Setup

Before beginning the Coolify installation, ensure your server environment meets these prerequisites:

  • Secure Shell (SSH) access to your Virtual Private Server (VPS).
  • curl utility installed. If not present, install it using your distribution's package manager (e.g., sudo apt update && sudo apt install curl -y on Debian/Ubuntu).
  • Docker Engine installed and running. This is fundamental for Coolify's containerized application deployment. Ensure Docker is properly configured, including user permissions to manage Docker without sudo if desired (add your user to the docker group: sudo usermod -aG docker $USER, then log out and back in).

Step-by-Step Manual Installation of Coolify

This section details the manual installation steps. It deviates from the typical script-based approach and focuses on a secure, ordered deployment.

1. Update System Packages

Begin by ensuring your system's package lists and installed packages are up-to-date. This mitigates potential conflicts and ensures you have the latest security patches.

sudo apt update && sudo apt upgrade -y

2. Install Docker Engine

If you haven't already, install Docker Engine. Follow the official Docker documentation for the most reliable installation method for your specific OS version, as repository versions can sometimes lag behind. For recent Ubuntu versions, the following commands often suffice, but verify with Docker's official guide.

# Add Docker's official GPG key:
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Set up the stable repository:
echo 
  "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu 
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine:
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io -y

# Verify Docker installation:
docker --version

After installation, it is crucial to verify that Docker is running and accessible. Check its status:

sudo systemctl status docker

If Docker is not running, start it:

sudo systemctl start docker
sudo systemctl enable docker

3. Download and Execute Coolify Installation Script

Coolify provides a shell script for installation. Even for manual setups, this script is often the most straightforward way to deploy the application itself. The difference lies in the prerequisites being met beforehand and potentially modifying the script or its execution context.

Download the latest installation script:

curl -fsSL https://coolify.io/install.sh -o install.sh

Before running, it's good practice to inspect the script for any commands you're not comfortable with, especially if you're concerned about security. You can view its contents with less install.sh.

Execute the script. This script will download the necessary Docker images and set up the Coolify application within containers.

sudo bash install.sh

The script will prompt you for necessary information, such as the domain name you wish to use for accessing the Coolify UI. Ensure you have a DNS record pointing to your server's IP address for this domain.

4. Initial Coolify Configuration

Once the installation script completes, Coolify should be accessible via the domain you provided. Navigate to this domain in your web browser.

The initial setup wizard will guide you through essential configurations:

  • Root Domain: Confirm or set the primary domain for Coolify.
  • Email Configuration: Set up SMTP details for sending notifications (e.g., password resets, deployment alerts). This is critical for operational awareness.
  • SSL/TLS: Coolify typically uses Let's Encrypt for automatic SSL certificate generation. Ensure your server's firewall allows traffic on ports 80 and 443.
  • Database: Coolify requires a database. It can set one up using Docker or connect to an external one. For simplicity, using the Docker-managed option is common.

5. Firewall Configuration

A secure VPS setup requires a properly configured firewall. You need to allow traffic for SSH, HTTP, and HTTPS, as well as any ports your deployed applications will use.

If you are using ufw (Uncomplicated Firewall), the basic rules would look like this:

sudo ufw allow OpenSSH
sudo ufw allow http
sudo ufw allow https
sudo ufw enable

You will need to open additional ports based on the applications you deploy through Coolify. For example, if you deploy a web application on port 3000, you would add sudo ufw allow 3000.

6. Post-Installation Steps and Security Best Practices

After a successful manual installation, consider these additional steps:

  • Regular Updates: Keep your server's operating system and Docker Engine updated. Regularly check for Coolify updates as well.
  • Backup Strategy: Implement a robust backup strategy for your server, including the Docker volumes that Coolify uses for its data and any databases it manages.
  • User Management: Carefully manage user access to both your server and the Coolify instance.
  • Review Logs: Periodically check Coolify's logs and Docker container logs for any anomalies or errors.

This manual setup ensures that even with newer Ubuntu versions not yet supported by the auto-installer, you can leverage Coolify's powerful deployment capabilities.