Coolify Reference Notes

Install and Setup

To get started, ssh into your server and run:

1. Install following the official documentation
   curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash

2. Add your current user to the Docker group, so you have permission to run docker commands. Note you will need to log out for changes to take effect.
   sudo usermod -aG docker $USER

Configure swap

On a small VM, extra swap can stop builds from running out of memory. The Debian installer usually creates a swap partition already. Check what is active:

sudo swapon --show

Example output when a swap partition is already enabled:

NAME           TYPE      SIZE USED PRIO
/dev/nvme0n1p3 partition  24G   0B   -2

If you need more swap or none is listed, follow Swap on the Debian Wiki for sizing, creating a swap file, /etc/fstab, and troubleshooting.

Usage with OrbStack

I use OrbStack for running VMs on Apple Silicon.

Setup

1. Create a new VM with the following settings:
   • Name: coolify (this name will map to the domain name of the VM)
   • Distribution: Debian
   • Version: stable (e.g. the latest non-testing version)
   • CPU Type: arm64
2. Once the machine is created, double click it in OrbStack to open a Terminal window
3. Install Coolify using the steps in Install and Setup above
4. Go to http://coolify.orb.local:8000 in a browser
5. Complete the setup as normal, registering the account, etc.

Once logged into the Coolify UI, make the following changes:

1. Disable the Proxy, as it doesn't work with mDNS
   • Go to Servers > localhost > Proxy
   • Click the "Switch Proxy" button (right of the Configuration heading)
   • Choose "None"

Quick Reference

• SSH command: ssh coolify@orb
• Coolify UI: http://coolify.orb.local:8000

App Configuration

Deploying apps with volumes

If you inject app config via a volume, ensure the Preserve Repository During Deployment option is checked - for example if your compose.yaml looks like. The format is host_path:container_path:

services:
   my-app:
      ...
      volumes:
         - my-config.yaml:/app/config.yaml

On the Application, open Configuration > General > Build and enable the Preserve Repository During Deployment checkbox.

Exposing apps via ports

By default, Coolify routes traffic through a proxy (Traefik) to expose apps via a domain name. In some scenarios it's preferable to expose apps via ports instead - for example in homelab environments.

For this the proxy can be disabled and apps configured to listen on ports instead.

Disable the Proxy

1. Go to Servers > localhost > Proxy
2. Click the "Switch Proxy" button (right of the Configuration heading)
3. Choose "None"

Configure a Docker Compose app to listen on ports

In the compose.yaml for the app, add the ports section. The format is host_port:container_port:

services:
   my-app:
      ...
      ports:
         - 3000:3000

Configure a Nixpack app to listen on ports

Configure the app as normal, then on the "Configuration" > "General" for the app:

1. Remove the value in "Domains"
2. For "Port Mappings", specify the port mapping in host_port:container_port format (e.g. 3000:3000). Ensure your app is configured to listen on the container port.
3. Click "Save"
4. Click "Redeploy"

The app should now be accessible via the port you specified.