Coolify Compose

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:

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:

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/

# compose.yml - can use build:
services:
  app:
    build:
      context: ./custom-image
      dockerfile: Dockerfile

Which Mode to Use?

Quick Start

Every Coolify template needs a header and magic variables:

# 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.

# 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

# 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

# ❌ Before
POSTGRES_PASSWORD=mysecretpassword
POSTGRES_USER=admin

# ✅ After  
POSTGRES_PASSWORD=$SERVICE_PASSWORD_POSTGRES
POSTGRES_USER=$SERVICE_USER_POSTGRES

3. Replace URLs with Magic Variables

# ❌ 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.

# ❌ Before
ports:
  - "3000:3000"

# ✅ After
environment:
  - SERVICE_URL_APP_3000  # Proxy routes to container port 3000
# No ports: needed

5. Add Health Checks

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
  interval: 5s
  timeout: 10s
  retries: 10

6. Use depends_on with Conditions

depends_on:
  db:
    condition: service_healthy

Magic Variables Reference

Coolify generates values using SERVICE_<TYPE>_<IDENTIFIER>:

Declaration vs Reference (Critical)

For SERVICE_URL, the port suffix configures proxy routing but is not part of the variable name:

# 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:

# 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:

SERVICE_URL_MY_SERVICE_3000  # ❌ Breaks parsing
SERVICE_URL_MY-SERVICE_3000  # ✅ Works

See references/magic-variables.md for complete list.

Coolify-Specific Extensions

Create Directory

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.

# 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:

services:
  migrate:
    command: ["npm", "run", "migrate"]
    exclude_from_hc: true

Common Patterns

Database Connection

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:

services:
  app:
    environment:
      - DB_PASS=$SERVICE_PASSWORD_POSTGRES
  db:
    environment:
      - POSTGRES_PASSWORD=$SERVICE_PASSWORD_POSTGRES  # Same value

Multi-Service URLs

services:
  frontend:
    environment:
      - SERVICE_URL_FRONTEND_3000
      - API_URL=$SERVICE_URL_API
  api:
    environment:
      - SERVICE_URL_API_8080=/api  # Path suffix

Health Check Patterns

# 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

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

Examples

First, check for an official template: Many popular services have official Coolify templates at 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:

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 — Complete variable type reference
• references/categories.md — Valid category values
• Official Coolify Compose Docs — Authoritative documentation
• Official Service Templates — Reference implementations for correct patterns

Multi-Service Conversion: Plausible Analytics

Changes Made

Key Patterns

Different Secret Types

# 64-char random string (for general secrets)
- SECRET_KEY_BASE=$SERVICE_BASE64_64_PLAUSIBLE

# Actual base64-encoded string (required by TOTP libraries)
- TOTP_VAULT_KEY=$SERVICE_REALBASE64_32_TOTP

Use REALBASE64 when the application expects actual base64 encoding (common for encryption keys, TOTP secrets).

Inline Configuration Files

Instead of mounting external files:

volumes:
  - type: bind
    source: ./clickhouse/clickhouse-config.xml
    target: /etc/clickhouse-server/config.d/logging.xml
    read_only: true
    content: |
      <clickhouse>
        <logger>
          <level>warning</level>
          ...
        </logger>
      </clickhouse>

Coolify creates this file at deploy time. The template is fully self-contained.

Dual Database Pattern

Plausible uses both PostgreSQL (metadata) and ClickHouse (events):

- DATABASE_URL=postgres://${SERVICE_USER_POSTGRES}:${SERVICE_PASSWORD_POSTGRES}@plausible-db:5432/...
- CLICKHOUSE_DATABASE_URL=http://plausible-events-db:8123/plausible_events_db

ClickHouse doesn't need credentials (internal network only), but PostgreSQL does.

Health Check Start Period

healthcheck:
  start_period: 45s  # Give app time to run migrations

Plausible runs database migrations on startup. The start_period prevents false failures during this initialization.

ulimits Preservation

ulimits:
  nofile:
    soft: 262144
    hard: 262144

ClickHouse needs high file descriptor limits. Standard Docker Compose features work in Coolify.

Migration Container Pattern (Alternative)

If migrations are slow, consider a separate migration container:

services:
  migrate:
    image: ghcr.io/plausible/community-edition:v3.0.1
    command: sh -c "/entrypoint.sh db createdb && /entrypoint.sh db migrate"
    exclude_from_hc: true  # Don't wait for this to stay running
    depends_on:
      plausible-db:
        condition: service_healthy

  plausible:
    command: /entrypoint.sh run  # Just run, no migrations
    depends_on:
      migrate:
        condition: service_completed_successfully

Coolify Compose Examples

Before/after examples showing standard Docker Compose files converted to Coolify templates.

Which Example to Use

Analyze the user's compose file:

Detection Rules

→ simple/

• Only 1 entry under services:
• No database images (postgres, mysql, mariadb, mongo, redis)
• Just needs URL routing + healthcheck

→ with-database/

• Exactly 2 services
• One is a database image (postgres:*, mysql:*, mariadb:*)
• App references database credentials in environment

→ multi-service/

• 3 or more services
• Multiple database images (e.g., postgres + clickhouse, postgres + redis)
• Config files mounted from host (./config.xml:/etc/app/config.xml)
• Init/migration containers that run once and exit

Each Example Contains

• before.yml — Standard Docker Compose (user's input)
• after.yml — Coolify-compatible template (desired output)
• notes.md — Explanation of each transformation

Simple Conversion: Uptime Kuma

Changes Made

Key Patterns

URL Generation

- SERVICE_URL_UPTIMEKUMA_3001

This single line: 1. Generates a URL like https://uptimekuma-abc123.example.com 2. Configures Traefik to route traffic to container port 3001 3. Creates an editable SERVICE_URL_UPTIMEKUMA variable in Coolify UI

Health Check

Uptime Kuma ships with a built-in healthcheck script at extra/healthcheck. Always prefer the application's native healthcheck when available.

Database Conversion: Ghost with MySQL

Changes Made

Key Patterns

Shared Credentials

The same identifier is used in both services:

# In ghost service
- database__connection__user=$SERVICE_USER_MYSQL
- database__connection__password=$SERVICE_PASSWORD_MYSQL

# In mysql service  
- MYSQL_USER=$SERVICE_USER_MYSQL
- MYSQL_PASSWORD=$SERVICE_PASSWORD_MYSQL

Coolify generates these once and injects the same value everywhere they're referenced.

Separate Root Password

MySQL needs a root password separate from the app user:

- MYSQL_ROOT_PASSWORD=$SERVICE_PASSWORD_MYSQLROOT

Using a different identifier (MYSQLROOT vs MYSQL) generates a different password.

Optional Defaults

- MYSQL_DATABASE=${MYSQL_DATABASE:-ghost}

This creates an editable variable in Coolify UI with "ghost" as the default value.

Health Check Dependency

depends_on:
  mysql:
    condition: service_healthy

Ghost won't start until MySQL's healthcheck passes, preventing connection errors on startup.

Template Categories

Valid values for the # category: header field.

Categories by Usage (from 337 Coolify templates)

Header Template

# documentation: https://example.com/docs
# slogan: Brief one-line description
# category: backend
# tags: keyword1, keyword2, keyword3
# logo: svgs/myservice.svg
# port: 3000

Optional Fields

Magic Environment Variables

Complete reference for Coolify's auto-generated environment variables.

Syntax

SERVICE_<TYPE>_<IDENTIFIER>

• TYPE: The generation method (see tables below)
• IDENTIFIER: Any alphanumeric name (used to reference the same value across services)

Credentials

Random Strings

⚠️ Note: BASE64 types are misleadingly named — they're just random alphanumeric strings, NOT base64-encoded. Use REALBASE64 for actual base64 encoding.

Actual Base64

Hex Strings

URLs & Domains

URL Examples

environment:
  # Basic URL generation
  - SERVICE_URL_APP                    # https://app-abc123.example.com
  
  # With port routing (proxy sends traffic to container port 3000)
  - SERVICE_URL_APP_3000               # https://app-abc123.example.com
  
  # With path
  - SERVICE_URL_API=/v1                # https://api-abc123.example.com/v1
  
  # With port AND path
  - SERVICE_URL_API_8080=/v1           # https://api-abc123.example.com/v1
  
  # FQDN only (no scheme)
  - SERVICE_FQDN_APP                   # app-abc123.example.com
  
  # Reference in other variables
  - PUBLIC_URL=$SERVICE_URL_APP
  - CORS_ORIGIN=${SERVICE_URL_APP}

⚠️ Port Syntax Warning

Underscores in the identifier break port parsing:

# ❌ WRONG - underscore before port
SERVICE_URL_MY_SERVICE_3000    # Coolify can't parse the port

# ✅ CORRECT - use hyphen
SERVICE_URL_MY-SERVICE_3000    # Works correctly

Special Types

These generate valid JWTs signed with SERVICE_PASSWORD_JWT for Supabase deployments.

Reusing Values

The same identifier always generates the same value:

services:
  app:
    environment:
      - DB_PASSWORD=$SERVICE_PASSWORD_POSTGRES
  
  worker:
    environment:
      - DB_PASSWORD=$SERVICE_PASSWORD_POSTGRES  # Identical value
  
  db:
    environment:
      - POSTGRES_PASSWORD=$SERVICE_PASSWORD_POSTGRES  # Identical value

Declaration vs Reference

environment:
  # Declaration - generates the URL AND sets up proxy routing
  - SERVICE_URL_APP_3000
  
  # Reference - uses the generated value in another variable
  - PUBLIC_URL=$SERVICE_URL_APP
  - WEBHOOK_URL=${SERVICE_URL_APP}/webhooks

Version Requirements

Magic environment variables in Git-sourced compose files require Coolify v4.0.0-beta.411 or later.

Official Coolify Docker Compose Documentation

Source: https://github.com/coollabsio/coolify-docs/blob/v4.x/docs/knowledge-base/docker/compose.md

This is the authoritative reference for Coolify Docker Compose behavior.

Key Concepts

Magic Environment Variables

Coolify generates dynamic environment variables using SERVICE_<TYPE>_<IDENTIFIER>:

• URL: Generates URL for the service. Add ports and paths as suffixes.
• FQDN: Generates FQDN (hostname without scheme). No port suffix needed.
• USER: Random 16-char string via Str::random(16)
• PASSWORD: Random password via Str::password(symbols: false). Use PASSWORD_64 for 64-char.
• BASE64: Random string via Str::random(32). Use BASE64_64 or BASE64_128 for longer.

Identifier Naming Rule

Identifiers with underscores (_) cannot use ports. Use hyphens (-) instead:

SERVICE_URL_APPWRITE_SERVICE_3000 ❌
SERVICE_URL_APPWRITE-SERVICE_3000 ✅

Complete Example from Official Docs

services:
  appwrite:
    environment:
      # http://appwrite-vgsco4o.example.com
      - SERVICE_URL_APPWRITE
      # http://appwrite-vgsco4o.example.com/v1/realtime
      - SERVICE_URL_APPWRITE=/v1/realtime
      # _APP_URL gets the value of SERVICE_URL_APPWRITE
      - _APP_URL=$SERVICE_URL_APPWRITE
      # http://appwrite-vgsco4o.example.com/ proxied to port 3000
      - SERVICE_URL_APPWRITE_3000
      # DOMAIN_NAME gets FQDN (appwrite-vgsco4o.example.com) - no port needed
      - DOMAIN_NAME=${SERVICE_FQDN_APPWRITE}
      # http://api-vgsco4o.example.com/api proxied to port 2000
      - SERVICE_URL_API_2000=/api
      # Password injected as SERVICE_SPECIFIC_PASSWORD
      - SERVICE_SPECIFIC_PASSWORD=${SERVICE_PASSWORD_APPWRITE}
  not-appwrite:
    environment:
      # Reuses password from Appwrite service
      - APPWRITE_PASSWORD=${SERVICE_PASSWORD_APPWRITE}
      # New URL: http://not-appwrite-vgsco4o.example.com/api
      - SERVICE_URL_API=/api

Key observations: 1. SERVICE_URL_APPWRITE_3000 declares URL AND configures proxy to port 3000 2. $SERVICE_URL_APPWRITE references the URL value (without port suffix) 3. ${SERVICE_FQDN_APPWRITE} is available without explicit declaration 4. Same identifier (e.g., SERVICE_PASSWORD_APPWRITE) = same value everywhere

Environment Variable Syntax

environment:
  - HARDCODED=hello                    # Not visible in Coolify UI
  - VARIABLE=${UI_VARIABLE}            # Editable in UI (empty)
  - WITH_DEFAULT=${VAR:-hello}         # Editable with default "hello"
  - REQUIRED=${VAR:?}                  # Required - blocks deploy if empty
  - REQUIRED_DEFAULT=${VAR:?default}   # Required with prefilled default

Storage Extensions

Create directory:

volumes:
  - type: bind
    source: ./data
    target: /app/data
    is_directory: true  # Coolify creates this

Create file with content:

volumes:
  - type: bind
    source: ./config.sql
    target: /docker-entrypoint-initdb.d/config.sql
    content: |
      ALTER USER authenticator WITH PASSWORD :'pgpass';

Exclude from Health Checks

services:
  migration:
    exclude_from_hc: true

Version Requirements

Magic Environment Variables in Compose files based on Git sources requires Coolify v4.0.0-beta.411 and above.