Install Coolify and Deploy Your First Application
Install Coolify on Debian or Ubuntu without exposing its dashboard, secure the instance, deploy an application over HTTPS, then manage updates and backups.
On this page
Your values
Enter them once and the commands in this guide update.
Coolify is a self-hosted platform that deploys your applications, databases and services on your own servers. It relies on Docker and on a reverse proxy that manages domains and HTTPS certificates.
By the end of this guide, the dashboard answers on https://coolify.your-domain.com, its direct ports are not exposed to the Internet, the administrator account is protected and a first application is running on https://app.your-domain.com.
Order a Server
This guide applies to servers that you administer yourself:
Prerequisites
- A server preferably dedicated to Coolify, running Debian 12 or 13, or Ubuntu 22.04 or 24.04
- At least 2 cores, 2 GB of RAM and 10 GB of free space, to be increased according to your applications and builds
- SSH access with
rootor a user that hassudo - Docker Engine 24 or later, installed with the guide Install Docker Engine and Docker Compose. Otherwise, the Coolify installer tries to install it on its own, but it refuses the snap version
- A domain name whose DNS zone you manage
- No service using ports 80 and 443, such as Nginx, Apache or Caddy
This guide uses version 4.7.5, the stable version at the time of writing. Check the latest version in the Coolify versions file.
Ports Used
| Port | Purpose | Exposure in this guide |
|---|---|---|
| 22/tcp | SSH, including Coolify's connection to the server | Open |
| 80/tcp | HTTP and certificate validation | Public, through the proxy |
| 443/tcp | HTTPS | Public, through the proxy |
| 443/udp | HTTP/3 | Public, through the proxy |
| 8000/tcp | Direct access to the dashboard | 127.0.0.1 only |
| 6001/tcp | Real-time updates | 127.0.0.1 only |
| 6002/tcp | Web terminal | 127.0.0.1 only |
| 8080/tcp | Port published by the default Traefik configuration | Removed in step 7 |
If you use UFW, keep SSH open with sudo ufw allow 22/tcp, without a limit rule: it can cut Coolify's repeated connections.
Step 1: Prepare the DNS
Create two A records pointing to YOUR_SERVER_IP:
| Name | Use |
|---|---|
coolify.your-domain.com |
Dashboard |
app.your-domain.com |
First application |
If your domain is managed at HostMyServers, follow the guide Point to an IP. Then check:
dig +short A coolify.your-domain.com
dig +short A app.your-domain.com
dig +short AAAA coolify.your-domain.comThe first two commands must return the server's address. If the last one returns an IPv6 address, it must also lead to this server, otherwise certificate creation may fail.
Step 2: Allow Coolify's SSH Connection
Coolify connects to the server over SSH with the root account and a dedicated key. Check the active setting:
sudo sshd -T | grep -i '^permitrootlogin'The values prohibit-password, without-password and yes are suitable. If you get no, allow root by key only:
echo 'PermitRootLogin prohibit-password' | sudo tee /etc/ssh/sshd_config.d/00-coolify.conf
sudo sshd -t
sudo systemctl reload sshKeep your session open and test a new connection before closing it.
If you followed Secure your server, SSH listens on port 2222. Replace 22 with 2222 in the UFW rules of this guide, then set this port in Servers > localhost > General once Coolify is installed.
Step 3: Restrict the Ports to the Local Address
Without this precaution, the dashboard would be published over HTTP on port 8000, and the first visitor could create the administrator account there. So create the customization file before the installation. Coolify keeps it during updates.
Switch to root:
sudo -i
mkdir -p /data/coolify/source
nano /data/coolify/source/docker-compose.custom.ymlPaste this content:
services:
coolify:
ports: !override
- "127.0.0.1:${APP_PORT:-8000}:8080"
- "127.0.0.1:${SOKETI_PORT:-6001}:6001"
- "127.0.0.1:6002:6002"Step 4: Install Coolify
Still as root, download the official script, read through it, then run it with the chosen version:
curl -fsSL https://cdn.coollabs.io/coolify/install.sh -o /root/coolify-install.sh
less /root/coolify-install.sh
bash /root/coolify-install.sh 4.7.5The script installs the required packages, adapts the Docker configuration, creates /data/coolify, generates Coolify's SSH key and starts its containers. It may restart Docker, which is one more reason to start from a new server.
At the end, it displays an http://...:8000 address. It will not respond from the Internet, and that is the intended result. Check the ports:
docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'The coolify line must show healthy and ports starting with 127.0.0.1:.
Step 5: Open the SSH Tunnel
In a terminal on your computer, open a tunnel to the three ports:
ssh -N -L 8000:127.0.0.1:8000 -L 6001:127.0.0.1:6001 -L 6002:127.0.0.1:6002 YOUR_USER@YOUR_SERVER_IPThe command stays active without printing anything. Leave this terminal open during the configuration. Traffic between your computer and the server is encrypted by SSH.
Step 6: Create the Administrator Account
Open http://localhost:8000 and create the account immediately, with a long and unique password. Coolify only accepts the first account for 10 minutes after it starts.
Then follow the wizard and choose to use this server (localhost). In Servers > localhost, the connection must be validated. If it is not, see the troubleshooting section.
Right away, copy the instance's encryption key into a password manager:
grep '^APP_KEY=' /data/coolify/source/.envStep 7: Start the Proxy
Open Servers > localhost > Proxy. Traefik is the default proxy.
In Configuration, remove the following line, which this setup does not need, then save:
- '8080:8080'Then click Start Proxy, or restart the proxy if it is already running. On the server, check that it is listening:
docker ps --filter name=coolify-proxy --format '{{.Names}} {{.Status}} {{.Ports}}'Ports 80 and 443 must appear on 0.0.0.0, and 8080 must no longer be in the list.
Step 8: Publish the Dashboard over HTTPS
Open Settings > General. In URL, enter:
https://coolify.your-domain.comLeave Redirect HTTP to HTTPS enabled, then click Save changes. After a few moments, open https://coolify.your-domain.com and check the certificate:
curl -I https://coolify.your-domain.comCheck that the data updates live and, if you use it, that the web terminal works. You can then close the tunnel with Ctrl+C. It remains your fallback access if the domain stops responding.
Step 9: Secure the Instance
| Setting | Location | Recommended value |
|---|---|---|
| Registrations | Settings > Advanced > Registration | Registration disabled |
| Two-factor authentication | Profile > Two-factor Authentication > Configure 2FA | Enabled, with recovery codes kept separately |
| API | Settings > Advanced > API access | Disabled if you do not use it |
| MCP server | Settings > Advanced | Disabled, unless you have a specific need |
| Allowed addresses | Settings > Advanced > Allowed IPs | Your addresses, if you enable the API |
| Team | Team | Minimum role for each member |
From another machine, without a tunnel, check what is reachable:
nmap -Pn -p 22,80,443,6001,6002,8000,8080 YOUR_SERVER_IPOnly 22, 80 and 443 must appear as open.
Step 10: Deploy a First Application
This example uses a ready-to-use image: it requires neither a Git repository nor a build.
- Open Projects, create a project named
demo, then open it. - Click + New (or Create New Resource), then choose Docker Image.
- Enter the image
nginx:1.30-alpineand continue. - In Ports Exposes, enter
80. - In Domains, click Add domain, choose
httpsand enterapp.your-domain.com. - Click Deploy and follow the deployment logs.
Then check the result:
curl -I https://app.your-domain.comThe response must be a 200 code, and the browser must display the Nginx welcome page with a valid certificate.
Deploy from a Public Git Repository
In the project, click + New, choose Public Repository, paste the repository's HTTPS address, then click Check repository. Then choose the Build pack, the application port and its domain, and start Deploy.
By default, the build runs on this server and can consume a lot of CPU and memory.
Update Coolify
A Coolify update does not change your applications, the system or Docker. Before starting it, read the release notes, wait for ongoing deployments to finish and make a backup.
From the Dashboard
Open Settings > Updates, keep the Stable channel, then click Upgrade now when a version is available. The Automatic updates setting determines whether Coolify installs new versions on its own. Disable it if you prefer to stay in control of the schedule.
From the Terminal
Run as root, giving the desired version without the v:
curl -fsSL https://cdn.coollabs.io/coolify/upgrade.sh | bash -s 4.7.5Do not use install.sh for a routine update: it resets owners and permissions under /data/coolify. The docker-compose.custom.yml file is still taken into account. Then check the version shown in the dashboard and, if needed, the /data/coolify/source/upgrade-*.log logs.
Back Up and Restore
Keep these items off the server:
| Item | Location | Why |
|---|---|---|
| Coolify database | .dmp backup |
Projects, settings and encrypted secrets |
APP_KEY key and .env file |
/data/coolify/source/.env |
Without this key, restored secrets are unreadable |
| SSH keys | /data/coolify/ssh/keys/ |
Connection to managed servers |
| Port customization | /data/coolify/source/docker-compose.custom.yml |
Keeps the ports protected |
| Application data | Volumes and databases | Not included in the Coolify backup |
From the Dashboard
Open Settings > Backup, click Configure backup, then Back up now. Check the result in Executions and use Download to get a copy. You can also add S3 storage. Leave Backup before update enabled to get a backup before each update started from the interface.
From the Terminal
As root:
mkdir -p /data/backups
docker exec coolify-db pg_dump --format=custom --no-acl --no-owner --username=coolify coolify > "/data/backups/coolify-db-$(date +%F).dmp"
test -s "/data/backups/coolify-db-$(date +%F).dmp" && echo OK
tar czf "/data/backups/coolify-files-$(date +%F).tar.gz" -C /data/coolify source/.env source/docker-compose.custom.yml ssh/keys
chmod 600 /data/backups/*These files contain secrets: copy them to an encrypted location.
Restore on the Same Server
Replace YYYY-MM-DD with the date of the backup. The current database will be replaced. First check that APP_KEY in /data/coolify/source/.env matches the saved key, then run as root:
docker stop coolify coolify-redis
docker exec -i coolify-db pg_restore --clean --if-exists --exit-on-error --no-acl --no-owner --username=coolify --dbname=coolify < /data/backups/coolify-db-YYYY-MM-DD.dmp
curl -fsSL https://cdn.coollabs.io/coolify/install.sh -o /root/coolify-install.sh
bash /root/coolify-install.sh 4.7.5Specify the version that was installed when the backup was made. On a new server, follow the official restore procedure, which also covers the SSH keys.
Troubleshooting
Setup window closed
The 10-minute window has passed. Restart Coolify, then reload the page:
docker restart coolifyThe :8000 Address Does Not Respond
This is normal from the Internet. Go through the tunnel from step 5 and open http://localhost:8000. If the tunnel fails, check the state of the containers with docker ps.
Data Does Not Update in the Dashboard
The real-time connection is not being established. With the tunnel, check that ports 6001 and 6002 are included in it. With the domain, check that the proxy is running and that no other proxy is blocking WebSockets.
Permission denied (publickey) During Server Validation
Coolify's key is missing for root, or root cannot log in. Check step 2. The installer does not keep the public key on disk: recompute it as root from the private key, then add it:
ssh-keygen -y -f /data/coolify/ssh/keys/id.root@host.docker.internal | sed 's/$/ coolify/' >> /root/.ssh/authorized_keysIf this file does not exist, list the folder with ls /data/coolify/ssh/keys/ and use the key found there.
The localhost Server Is Unreachable or Unstable
Coolify reaches the server from its Docker network. A ufw limit 22/tcp rule or an SSH restriction to your address alone can block it. Replace the limit with sudo ufw allow 22/tcp, or allow the Coolify network:
docker network inspect coolify --format '{{(index .IPAM.Config 0).Subnet}}'
sudo ufw allow from SUBNET to any port 22 proto tcpReplace SUBNET with the value displayed.
The Proxy Does Not Start: address already in use
Another service is using port 80 or 443:
sudo ss -ltnp | grep -E ':(80|443) 'Stop and disable that service, then start the proxy again.
The Proxy Is Only Reachable Locally
Check that /etc/docker/daemon.json contains neither "ip": "127.0.0.1" nor host_binding_ipv4. Remove these keys, restart Docker, then the proxy.
The Certificate Is Not Valid (TRAEFIK DEFAULT CERT)
Let's Encrypt could not validate the domain. Check the A and AAAA records, then access to port 80 from outside. If the domain goes through Cloudflare's proxy, disable it for the duration of the validation or use a DNS challenge. If the port remains unreachable while everything is correct on the server, contact support from your client area.
502 Bad Gateway Error
The proxy reaches the container, but not the application. Check that Ports Exposes matches the application's actual port, and that the application listens on 0.0.0.0 and not on 127.0.0.1.
no available server
Traefik cannot find any healthy container for this domain. Check the deployment status, the application's health check and the spelling of the domain in Domains.
Port 8000 Remains Accessible from the Internet
The customization file is not applied. Check its location and syntax, then apply it as root:
cd /data/coolify/source
docker compose --env-file .env -f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.custom.yml config --quiet
docker compose --env-file .env -f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.custom.yml up -d --remove-orphansThe Server Slows Down Heavily During a Deployment
The build consumes the server's resources. Deploy an already built image, build elsewhere (for example in your CI) or increase the resources.
Invalid MAC After a Restore
The APP_KEY does not match the one in the backup. Put the saved key back in /data/coolify/source/.env, then run the installer again with the same version.