How to Deploy Coolify on Docker (Step-by-Step)
Overview
Coolify is a self-hosted PaaS that simplifies deploying applications, databases, and services. Below is a modern, secure, and production-ready Docker Compose file you can paste directly into Portainer Stacks to get running quickly.
How to Deploy Coolify
Need help right now? Hire a freelancer to set this up end-to-end. If you need live agent support, talk on the website chat.
Quick Start
- Generate Secrets: Before deploying, you need two keys. Run these commands on your server:
# 1. Generate a 64-char hex secret for Coolify openssl rand -hex 32 # 2. Generate a base64 Laravel APP_KEY docker run --rm coollabsio/coolify:latest php -r "echo 'base64:'.base64_encode(random_bytes(32)).PHP_EOL;" - Configure Compose: Paste the Compose file below into Portainer → Stacks → Add stack. Replace the `REPLACE_WITH...` placeholders with the keys you just generated.
- Deploy & Access: Click "Deploy the stack" and wait about a minute. Then open `http://
:4000` in your browser to complete the setup.
Production-Ready docker-compose.yml
This configuration is confirmed to work and includes all necessary components, healthchecks, and environment variables for a stable setup.
version: "3.8"
services:
coolify:
image: coollabsio/coolify:latest
container_name: coolify
restart: unless-stopped
ports:
- "4000:8080"
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- /opt/coolify:/data
environment:
- COOLIFY_APP_ID=coolify
- COOLIFY_SECRET_KEY=REPLACE_WITH_HEX64
- APP_KEY=REPLACE_WITH_BASE64_APP_KEY
- DATABASE_URL=postgresql://coolify:coolifypass123@coolify-db:5432/coolify
- COOLIFY_DATABASE_URL=postgresql://coolify:coolifypass123@coolify-db:5432/coolify
- DB_CONNECTION=pgsql
- DB_HOST=coolify-db
- DB_PORT=5432
- DB_DATABASE=coolify
- DB_USERNAME=coolify
- DB_PASSWORD=coolifypass123
- COOLIFY_REDIS_URL=redis://coolify-redis:6379
depends_on:
- db
- redis
db:
image: postgres:15
container_name: coolify-db
restart: unless-stopped
environment:
- POSTGRES_USER=coolify
- POSTGRES_PASSWORD=coolifypass123
- POSTGRES_DB=coolify
volumes:
- /opt/coolify/db:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U coolify -d coolify"]
interval: 10s
timeout: 5s
retries: 10
redis:
image: redis:alpine
container_name: coolify-redis
restart: unless-stopped
volumes:
- /opt/coolify/redis:/data
Troubleshooting FAQ
Why does my browser say "Connection Refused"?
This is usually a port mapping issue. The Coolify container listens on port `8080` internally. Your `docker-compose.yml` must map an external port to it, like `ports: ["4000:8080"]`. Using `3000` as the internal port will fail.
I see a "500 Internal Server Error". How do I fix it?
A 500 error means the application is running but failing. The most common cause is a missing Laravel `APP_KEY`. Make sure you generate this key (see Quick Start) and add it to the `environment` section of the `coolify` service in your compose file.
My logs show database errors like "connection failed".
This means your `coolify` container can't talk to the `coolify-db` container. Check three things: 1) The hostname in your `DATABASE_URL` must match the `container_name` of your database service (e.g., `...@coolify-db:5432...`). 2) The password must be identical in all `DB_PASSWORD` and `DATABASE_URL` variables. 3) Ensure `depends_on: - db` is present.
What's the difference between the two secret keys?
`COOLIFY_SECRET_KEY` is used to encrypt sensitive data you store *in* Coolify (like server keys). `APP_KEY` is used by the underlying Laravel framework for sessions and internal encryption. You need to generate both before your first launch and save them securely.
How do I backup and restore everything?
First, back up the persistent data by archiving the `/opt/coolify` directory on your host. Second, and most importantly, save the `COOLIFY_SECRET_KEY` and `APP_KEY` from your compose file. To restore, place the `/opt/coolify` directory back and deploy using the *exact same* compose file with the same keys.
