---
name: coolify-compose
description: Convert Docker Compose files to Coolify templates. Use when creating Coolify services, converting docker-compose.yml for Coolify deployment, working with SERVICE_URL/SERVICE_PASSWORD magic variables, or troubleshooting Coolify compose errors.
---
# Coolify Docker Compose
Convert standard Docker Compose files into Coolify-compatible templates with automatic credential generation, dynamic URLs, and one-click deployment.
## Two Deployment Modes
Coolify supports two ways to deploy compose files with different capabilities:
### 1. Raw Compose (Paste Content)
Paste compose YAML directly into Coolify's UI. **Limited feature set:**
| Feature | Supported |
|---------|-----------|
| `image:` | ✅ Yes |
| `build:` | ❌ No - must use pre-built images |
| External config files | ❌ No - must use inline `content:` |
| YAML anchors (`&`, `*`) | ✅ Yes - resolved by YAML parser |
| Coolify magic variables | ✅ Yes |
| `content:` for inline files | ✅ Yes |
**Use when:** Quick deployments, simple services, no custom images needed.
### 2. Repository Mode (Git URL)
Point Coolify to a Git repository containing your compose file. **Full Docker Compose features:**
| Feature | Supported |
|---------|-----------|
| `image:` | ✅ Yes |
| `build:` | ✅ Yes - builds from Dockerfile in repo |
| External config files | ✅ Yes - relative paths work |
| Coolify magic variables | ✅ Yes |
| `content:` for inline files | ✅ Yes |
**Use when:** Custom images needed, complex multi-file setups, existing docker-compose.yml in a repo.
**Repository setup:**
```
my-service/
├── compose.yml # or docker-compose.yml
├── custom-image/
│ ├── Dockerfile
│ └── config.sql
└── other-files/
```
```yaml
# compose.yml - can use build:
services:
app:
build:
context: ./custom-image
dockerfile: Dockerfile
```
### Which Mode to Use?
| Original compose has... | Recommended mode |
|------------------------|------------------|
| Only `image:` references | Either works |
| `build:` directives | Repository mode |
| External config files to mount | Repository mode (or use `content:` in raw) |
| Single simple service | Raw mode is faster |
## Quick Start
Every Coolify template needs a header and magic variables:
```yaml
# documentation: https://example.com/docs
# slogan: Brief description of the service
# category: backend
# tags: api, database, docker
# logo: svgs/myservice.svg
# port: 3000
services:
app:
image: myapp:latest
environment:
- SERVICE_URL_APP_3000 # Generates URL, routes proxy to port 3000
- DATABASE_URL=postgres://${SERVICE_USER_POSTGRES}:${SERVICE_PASSWORD_POSTGRES}@db:5432/mydb
depends_on:
db:
condition: service_healthy
healthcheck:
test: ["CMD", "wget", "-q", "--spider", "http://localhost:3000/health"]
interval: 5s
timeout: 10s
retries: 10
db:
image: postgres:16-alpine
environment:
- POSTGRES_USER=$SERVICE_USER_POSTGRES
- POSTGRES_PASSWORD=$SERVICE_PASSWORD_POSTGRES
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER}"]
interval: 5s
timeout: 10s
retries: 10
```
## Conversion Checklist
When converting a standard `docker-compose.yml`:
### 0. Check for `build:` Directives
If the compose has `build:` entries:
- **Repository mode:** Keep them. Coolify will build from the Dockerfile.
- **Raw mode:** Replace with pre-built `image:` references or find equivalent images.
```yaml
# Original with build:
services:
custom-db:
build: ./custom-postgres
# Raw mode: find or create pre-built image
custom-db:
image: your-registry.com/custom-postgres:latest
# Repository mode: keep build:, include Dockerfile in repo
custom-db:
build:
context: ./custom-postgres
dockerfile: Dockerfile
```
### 1. Add Header Metadata
```yaml
# documentation: https://... # Required: URL to official docs
# slogan: ... # Required: One-line description
# category: ... # Required: backend, cms, monitoring, etc.
# tags: ... # Required: Comma-separated search terms
# logo: svgs/....svg # Required: Path in Coolify's svgs/ folder
# port: ... # Recommended: Main service port
```
### 2. Replace Hardcoded Credentials
```yaml
# ❌ Before
POSTGRES_PASSWORD=mysecretpassword
POSTGRES_USER=admin
# ✅ After
POSTGRES_PASSWORD=$SERVICE_PASSWORD_POSTGRES
POSTGRES_USER=$SERVICE_USER_POSTGRES
```
### 3. Replace URLs with Magic Variables
```yaml
# ❌ Before
APP_URL=https://myapp.example.com
# ✅ After
- SERVICE_URL_APP_3000 # Declares URL + proxy routing
- APP_URL=$SERVICE_URL_APP # References it
```
### 4. Remove `ports:` for Proxied Services
Coolify's Traefik proxy handles routing. Only keep `ports:` for SSH, UDP, or proxy bypass.
```yaml
# ❌ Before
ports:
- "3000:3000"
# ✅ After
environment:
- SERVICE_URL_APP_3000 # Proxy routes to container port 3000
# No ports: needed
```
### 5. Add Health Checks
```yaml
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
interval: 5s
timeout: 10s
retries: 10
```
### 6. Use `depends_on` with Conditions
```yaml
depends_on:
db:
condition: service_healthy
```
## Magic Variables Reference
Coolify generates values using `SERVICE_<TYPE>_<IDENTIFIER>`:
| Type | Example | Result |
|------|---------|--------|
| `PASSWORD` | `SERVICE_PASSWORD_DB` | Random password |
| `PASSWORD_64` | `SERVICE_PASSWORD_64_KEY` | 64-char password |
| `USER` | `SERVICE_USER_ADMIN` | Random 16-char string |
| `BASE64_64` | `SERVICE_BASE64_64_SECRET` | 64-char random string |
| `REALBASE64_64` | `SERVICE_REALBASE64_64_JWT` | Actual base64-encoded string |
| `HEX_32` | `SERVICE_HEX_32_KEY` | 64-char hex string |
| `URL` | `SERVICE_URL_APP_3000` | `https://app-uuid.example.com` + proxy |
| `FQDN` | `SERVICE_FQDN_APP` | `app-uuid.example.com` (no scheme, no port suffix) |
### Declaration vs Reference (Critical)
For `SERVICE_URL`, the port suffix configures proxy routing but is **not part of the variable name**:
```yaml
# Declare WITH port suffix (configures proxy to route to port 3000)
- SERVICE_URL_MYAPP_3000
# Reference WITHOUT port suffix (gets the URL value)
- APP_URL=$SERVICE_URL_MYAPP
- WEBHOOK_URL=${SERVICE_URL_MYAPP}/webhooks
```
`SERVICE_FQDN` is automatically available when `SERVICE_URL` is declared — no separate declaration needed:
```yaml
# This single declaration...
- SERVICE_URL_MYAPP_3000
# ...makes BOTH of these available:
- FULL_URL=$SERVICE_URL_MYAPP # https://myapp-uuid.example.com
- HOSTNAME=${SERVICE_FQDN_MYAPP} # myapp-uuid.example.com
```
**⚠️ Important:** Use hyphens, not underscores, before port numbers:
```yaml
SERVICE_URL_MY_SERVICE_3000 # ❌ Breaks parsing
SERVICE_URL_MY-SERVICE_3000 # ✅ Works
```
See [references/magic-variables.md](references/magic-variables.md) for complete list.
## Coolify-Specific Extensions
### Create Directory
```yaml
volumes:
- type: bind
source: ./data
target: /app/data
is_directory: true # Coolify creates this
```
### Create File with Content
Useful in **raw mode** when you can't reference external files. In **repository mode**, you can just mount files normally.
```yaml
# Raw mode: embed file content inline
volumes:
- type: bind
source: ./config.json
target: /app/config.json
content: |
{"key": "${SERVICE_PASSWORD_APP}"}
# Repository mode: reference actual file in repo
volumes:
- ./config/settings.json:/app/config.json:ro
```
### Exclude from Health Checks
For migration/init containers that exit after running:
```yaml
services:
migrate:
command: ["npm", "run", "migrate"]
exclude_from_hc: true
```
## Common Patterns
### Database Connection
```yaml
environment:
- DATABASE_URL=postgres://${SERVICE_USER_POSTGRES}:${SERVICE_PASSWORD_POSTGRES}@db:5432/${POSTGRES_DB:-myapp}
```
### Shared Credentials
Same `SERVICE_PASSWORD_*` identifier = same value across all services:
```yaml
services:
app:
environment:
- DB_PASS=$SERVICE_PASSWORD_POSTGRES
db:
environment:
- POSTGRES_PASSWORD=$SERVICE_PASSWORD_POSTGRES # Same value
```
### Multi-Service URLs
```yaml
services:
frontend:
environment:
- SERVICE_URL_FRONTEND_3000
- API_URL=$SERVICE_URL_API
api:
environment:
- SERVICE_URL_API_8080=/api # Path suffix
```
## Health Check Patterns
```yaml
# HTTP
test: ["CMD", "wget", "--spider", "-q", "http://localhost:8080"]
# PostgreSQL
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
# MySQL/MariaDB
test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
# Redis
test: ["CMD", "redis-cli", "ping"]
# Always pass (use sparingly)
test: ["CMD", "echo", "ok"]
```
## Environment Variable Syntax
```yaml
environment:
- NODE_ENV=production # Hardcoded, hidden from UI
- API_KEY=${API_KEY} # Editable in UI (empty)
- LOG_LEVEL=${LOG_LEVEL:-info} # Editable with default
- SECRET=${SECRET:?} # Required - blocks deploy if empty
```
## Troubleshooting
| Problem | Solution |
|---------|----------|
| "No Available Server" error | Check `docker ps` for unhealthy containers; verify healthcheck passes |
| Variables not in Coolify UI | Use `${VAR}` syntax; hardcoded `VAR=value` won't appear |
| Magic variables not generating | Check spelling; ensure `SERVICE_` prefix; verify Coolify v4.0.0-beta.411+ |
| Port routing broken | Use `SERVICE_URL_NAME_PORT`; avoid underscores before port; remove `ports:` |
## Examples
**First, check for an official template:** Many popular services have official Coolify templates at [github.com/coollabsio/coolify/tree/main/templates/compose](https://github.com/coollabsio/coolify/tree/main/templates/compose). If one exists, use it as the reference for correct patterns.
When converting a compose file without an official template, analyze it and use the matching example:
| Compose file has... | Use example |
|---------------------|-------------|
| 1 service, no database | [examples/simple/](examples/simple/) |
| 2 services: app + database (postgres/mysql/mariadb) | [examples/with-database/](examples/with-database/) |
| 3+ services, or mounted config files, or multiple databases | [examples/multi-service/](examples/multi-service/) |
**Quick analysis:**
- Count the `services:` — if just 1, use `simple/`
- Look for `postgres`, `mysql`, `mariadb`, `mongo` images — if 1 database, use `with-database/`
- Look for mounted `.xml`, `.json`, `.yml` config files — if present, use `multi-service/`
- Look for `clickhouse`, `redis`, multiple databases — use `multi-service/`
## References
- [references/magic-variables.md](references/magic-variables.md) — Complete variable type reference
- [references/categories.md](references/categories.md) — Valid category values
- [Official Coolify Compose Docs](https://coolify.io/docs/knowledge-base/docker/compose) — Authoritative documentation
- [Official Service Templates](https://github.com/coollabsio/coolify/tree/main/templates/compose) — Reference implementations for correct patterns