Skip to content

Installation - Self-hosted

Prerequisites

Server Requirements

You need a server with SSH access. This can be:

  • A VPS
  • A Dedicated Server
  • A VM in Proxmox
  • A Raspberry Pi (for all compatible models read the Raspberry Pi OS Setup Guide prerequisites)
  • Any other server with SSH access

Supported Operating Systems

  • Debian based Linux distributions (Debian, Ubuntu, etc.)
  • Redhat based Linux distributions (CentOS, Fedora, Redhat, AlmaLinux, Rocky, Asahi, etc.)
  • SUSE based Linux distributions (SLES, SUSE, openSUSE, etc.)
  • Arch Linux
  • Raspberry Pi OS 64-bit (Raspbian)
  • Alpine Linux

Supported Architectures

We only support 64-bit architectures:

  • AMD64
  • ARM64

Minimum Hardware Requirements

Server Requirements for Coolify

  • 2 Core CPU
  • 2 GBs memory (RAM)
  • 30+ GB of storage for the images

If you build and host on the same server as Coolify and your builds are utilizing all available memory, this may cause the server to become unresponsive or even crash. To prevent this, consider enabling swap space on your server (or paying for more resources).

Server Requirements for Your Resources

Choosing your server resources depends on your usage. If you are planning to run a lot of things, you should consider buying a server with more resources.

Hosting Supabase, Appwrite or Posthog requires more resources than hosting a static site (waay more).

Installation Methods

  1. Verify Prerequisites

    • The curl command is installed on your server (this will most likely be the case)
    • Your firewall is configured with the required ports (setup guide) (if you are and advanced user you can have this configured differently)
  2. Run the installation script

    Terminal window
    curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

    View the Scripts Source Code

  3. Access coolify

    • You can find the URL of your coolify instance in the installation output.
    • It is recommended to use the PrivateIP to access coolify as it is more secure (a VPN setup to your Server is needed for that to work).

The installer does the following:

  • Installs required tools (curl wget git jq openssl)
  • Installs Docker Engine (26+)
  • Configures Docker logging
  • Configures Docker daemon with default address pools
  • Creates directory structure at /data/coolify
  • Sets up SSH keys for server management
  • Installs and starts Coolify

2. Manual Installation

For users who prefer more control over the installation process.

  1. SSH Enabled Make sure SSH is enabled and you can connect to your server with SSH from your local machine with root user: more details here.

  2. Curl Installed Make sure curl command is available on your server.

  3. Install Docker Engine (24+) Follow the official documentation to install Docker Engine on your server: Docker Engine Installation.

  4. Create Directories Create the base configuration directories under /data/coolify.

    Terminal window
    mkdir -p /data/coolify/{source,ssh,applications,databases,backups,services,proxy,webhooks-during-maintenance}
    mkdir -p /data/coolify/ssh/{keys,mux}
    mkdir -p /data/coolify/proxy/dynamic
  5. Generate SSH Key Generate an SSH key for Coolify to be able to manage this server from itself.

    Terminal window
    ssh-keygen -f /data/coolify/ssh/keys/[email protected] -t ed25519 -N '' -C root@coolify
  6. Setup Your SSH Key Add your public SSH key to ~/.ssh/authorized_keys. This will allow Coolify to connect to this server from itself.

    Terminal window
    cat /data/coolify/ssh/keys/[email protected] >>~/.ssh/authorized_keys
    chmod 600 ~/.ssh/authorized_keys
  7. Setup Configuration Files Copy the docker-compose.yml, docker-compose.prod.yml, .env.production & upgrade.sh files from Coolify’s CDN to /data/coolify/source.

    Terminal window
    curl -fsSL https://cdn.coollabs.io/coolify/docker-compose.yml -o /data/coolify/source/docker-compose.yml
    curl -fsSL https://cdn.coollabs.io/coolify/docker-compose.prod.yml -o /data/coolify/source/docker-compose.prod.yml
    curl -fsSL https://cdn.coollabs.io/coolify/.env.production -o /data/coolify/source/.env
    curl -fsSL https://cdn.coollabs.io/coolify/upgrade.sh -o /data/coolify/source/upgrade.sh
  8. Set Permissions Set permissions for all the files and directories.

    Terminal window
    chown -R 9999:root /data/coolify
    chmod -R 700 /data/coolify
  9. Generate Values Generate values for the following variables in /data/coolify/source/.env.

    Terminal window
    sed -i "s|APP_ID=.*|APP_ID=$(openssl rand -hex 16)|g" /data/coolify/source/.env
    sed -i "s|APP_KEY=.*|APP_KEY=base64:$(openssl rand -base64 32)|g" /data/coolify/source/.env
    sed -i "s|DB_PASSWORD=.*|DB_PASSWORD=$(openssl rand -base64 32)|g" /data/coolify/source/.env
    sed -i "s|REDIS_PASSWORD=.*|REDIS_PASSWORD=$(openssl rand -base64 32)|g" /data/coolify/source/.env
    sed -i "s|PUSHER_APP_ID=.*|PUSHER_APP_ID=$(openssl rand -hex 32)|g" /data/coolify/source/.env
    sed -i "s|PUSHER_APP_KEY=.*|PUSHER_APP_KEY=$(openssl rand -hex 32)|g" /data/coolify/source/.env
    sed -i "s|PUSHER_APP_SECRET=.*|PUSHER_APP_SECRET=$(openssl rand -hex 32)|g" /data/coolify/source/.env
  10. Default Docker Network Make sure the default coolify Docker network is available.

    Terminal window
    docker network create --attachable coolify
  11. Start Coolify

    Terminal window
    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
  12. Open Coolify’s UI Now you can access Coolify on port http://<ip>:8000 of your server.

3. Docker Desktop Installation

For local development and testing purposes only.

  • Install Docker Desktop for Windows.
  • Create a directory that will hold all your Coolify related data. For example in your User directory: C:\Users\yourusername\coolify.
  • Copy docker-compose.windows.yml and .env.windows-docker-desktop.example to the directory you created in the previous step.
  • Rename docker-compose.windows.yml to docker-compose.yml.
  • Rename .env.windows-docker-desktop.example to .env.
  • Create a coolify docker network with docker network create coolify.
  • Optional: Change the values in .env file.
  • Start Coolify with docker compose up command.
  • You can access Coolify on port localhost:8000 of your machine.

Debugging

Expired GitHub Personal Access Token

If you encounter an error like Error response from daemon: Head "https://ghcr.io/v2/coollabsio/coolify-helper/manifests/1.0.1": unauthorized: authentication required, it means Docker cannot access the GitHub Container Registry.

To fix this, either:

  • Log out of the GitHub Container Registry or
  • Renew your GitHub Personal Access Token

Raspberry Pi Crashes

If you are using a Raspberry Pi with only 2GB of RAM, you may experience system crashes even with swap space enabled. This probably occurs because Raspberry PIs often use SD cards which are slower than SSDs and can be unstable.

The solution is to either:

  • Upgrade to a modern Raspberry Pi with 4GB+ of RAM, or
  • Limit Docker’s memory usage by adding the following to your /etc/docker/daemon.json file:
{
"memory": "1.8g"
}