Coolify

Coolify

Overview

Coolify is a self-hosted PaaS (Vercel/Netlify alternative) that deploys applications, databases, and services on your own infrastructure. It provides a REST API for programmatic control, supports multiple build packs, and uses Traefik for reverse proxy and SSL.

When to use: Deploying applications to self-hosted infrastructure, managing databases and services through API, automating deployments via CI/CD, self-hosting without vendor lock-in.

When NOT to use: Initial Coolify server installation (use the official install script via browser), managing Coolify's own infrastructure (Postgres, Redis — managed internally), or when a managed platform (Vercel, Railway) meets your needs without self-hosting requirements.

Quick Reference

Common Mistakes

Delegation

• API exploration: Use Explore agent to discover existing Coolify resources
• Dockerfile optimization: Use Task agent to review Dockerfiles for Coolify deployment
• CI/CD pipeline design: Use Plan agent for deployment workflow strategy

If the docker skill is available, delegate Dockerfile authoring, multi-stage builds, and image optimization to it.

If the github-actions skill is available, delegate workflow syntax and CI pipeline patterns to it.

If the ci-cd-architecture skill is available, delegate deployment strategy and environment promotion to it.

References

• API: authentication, endpoints, common operations, and permission scopes
• Deployment: auto-deploy, webhooks, GitHub Actions, and CI/CD pipelines
• Build packs: Nixpacks, Dockerfile, Compose conventions, and configuration

API Patterns

Authentication

All API requests require a Bearer token created in the Coolify dashboard under Settings > API Tokens.

curl -s \
  -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Accept: application/json" \
  https://coolify.example.com/api/v1/version

The Accept: application/json header is required — without it, some endpoints return "Unauthenticated" even with a valid token.

Permission Scopes

Fields like is_auto_deploy_enabled, API keys, and passwords are redacted unless the token has view:sensitive or * scope.

Environment Variables

Set the Coolify instance URL and token as environment variables:

export COOLIFY_URL="https://coolify.example.com"
export COOLIFY_TOKEN="1|your-token-here"

Common Endpoints

Applications

# List all applications
curl -s -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Accept: application/json" \
  "$COOLIFY_URL/api/v1/applications" | jq .

# Get application details
curl -s -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Accept: application/json" \
  "$COOLIFY_URL/api/v1/applications/<uuid>"

# Create a public Git application
curl -s -X POST \
  -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "project_uuid": "<project-uuid>",
    "server_uuid": "<server-uuid>",
    "environment_name": "production",
    "git_repository": "https://github.com/org/repo",
    "git_branch": "main",
    "build_pack": "nixpacks",
    "ports_exposes": "3000"
  }' \
  "$COOLIFY_URL/api/v1/applications/public"

# Update application settings
curl -s -X PATCH \
  -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "is_auto_deploy_enabled": true,
    "health_check_path": "/health",
    "health_check_interval": 30
  }' \
  "$COOLIFY_URL/api/v1/applications/<uuid>"

# Delete application
curl -s -X DELETE \
  -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Accept: application/json" \
  "$COOLIFY_URL/api/v1/applications/<uuid>"

Deployments

# Trigger deployment (by UUID)
curl -s -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Accept: application/json" \
  "$COOLIFY_URL/api/v1/deploy?uuid=<app-uuid>&force=true"

# Trigger deployment (by webhook URL)
curl -s -H "Authorization: Bearer $COOLIFY_TOKEN" \
  "$COOLIFY_URL/api/v1/applications/<uuid>/deploy"

# List deployments
curl -s -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Accept: application/json" \
  "$COOLIFY_URL/api/v1/deployments"

# Get deployment details
curl -s -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Accept: application/json" \
  "$COOLIFY_URL/api/v1/deployments/<deployment-uuid>"

Databases

# List all databases
curl -s -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Accept: application/json" \
  "$COOLIFY_URL/api/v1/databases"

# Create a PostgreSQL database
curl -s -X POST \
  -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "project_uuid": "<project-uuid>",
    "server_uuid": "<server-uuid>",
    "environment_name": "production",
    "type": "postgresql",
    "name": "my-database"
  }' \
  "$COOLIFY_URL/api/v1/databases"

Services

# List all services (280+ one-click services)
curl -s -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Accept: application/json" \
  "$COOLIFY_URL/api/v1/services"

# Get service details
curl -s -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Accept: application/json" \
  "$COOLIFY_URL/api/v1/services/<uuid>"

Projects and Environments

# List projects
curl -s -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Accept: application/json" \
  "$COOLIFY_URL/api/v1/projects"

# Get project with environments
curl -s -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Accept: application/json" \
  "$COOLIFY_URL/api/v1/projects/<uuid>"

Servers

# List servers (requires elevated permissions)
curl -s -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Accept: application/json" \
  "$COOLIFY_URL/api/v1/servers"

# Get server details
curl -s -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Accept: application/json" \
  "$COOLIFY_URL/api/v1/servers/<uuid>"

Updatable Application Fields

The PATCH endpoint accepts these fields:

Error Handling

Build Packs

Build Pack Comparison

Set the build pack via API:

curl -s -X PATCH \
  -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"build_pack": "nixpacks"}' \
  "$COOLIFY_URL/api/v1/applications/<uuid>"

Valid values: nixpacks, dockerfile, dockercompose

Nixpacks

Nixpacks auto-detects the language and framework from source code, generates a Dockerfile, builds, and deploys — zero configuration needed.

Supported Languages

Node.js, Python, Go, Rust, Ruby, PHP, Java, .NET, Elixir, Haskell, Clojure, Scala, Swift, Dart, Crystal, Zig, and more.

Customization with nixpacks.toml

Place nixpacks.toml in the repository root to override auto-detection:

# Custom build phases
[phases.setup]
nixPkgs = ["nodejs_20", "pnpm"]

[phases.install]
cmds = ["pnpm install --frozen-lockfile"]

[phases.build]
cmds = ["pnpm build"]

# Environment variables baked into the image
[variables]
NODE_ENV = "production"

# Start command
[start]
cmd = "pnpm start"

Common Nixpacks Overrides

# Pin Node.js version
[phases.setup]
nixPkgs = ["nodejs_24"]

# Add system dependencies (e.g., for sharp/canvas)
[phases.setup]
nixPkgs = ["nodejs_24", "vips", "pkg-config"]
aptPkgs = ["libvips-dev"]

# Custom install + build
[phases.install]
cmds = ["npm ci"]

[phases.build]
cmds = ["npm run build"]

# Cache directories between builds
[phases.install]
cacheDirectories = ["/root/.npm"]

Nixpacks Environment Variables

Override behavior without nixpacks.toml by setting environment variables in Coolify:

Dockerfile

Full control over the build. Set build_pack to dockerfile and Coolify reads the Dockerfile from the repository.

API Configuration

curl -s -X PATCH \
  -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "build_pack": "dockerfile",
    "dockerfile_location": "/Dockerfile",
    "build_command": null,
    "start_command": null
  }' \
  "$COOLIFY_URL/api/v1/applications/<uuid>"

Build Arguments

Coolify can inject build arguments during the build process. Configure them in the application's Advanced menu. The SOURCE_COMMIT variable (Git commit hash) is available but disabled by default to preserve Docker cache.

Docker Compose

The docker-compose.yaml file is the single source of truth. Coolify reads it and manages the stack.

Coolify-Specific Labels

Coolify auto-applies these labels to managed containers:

labels:
  coolify.managed: 'true'
  coolify.applicationId: '<app-id>'
  coolify.type: 'application'

Traefik Integration

Make services internet-accessible with Traefik labels:

services:
  app:
    build: .
    labels:
      - 'traefik.enable=true'
      - 'traefik.http.routers.app.rule=Host(`app.example.com`)'
      - 'traefik.http.routers.app.entrypoints=https'
      - 'traefik.http.routers.app.tls=true'
      - 'traefik.http.routers.app.tls.certresolver=letsencrypt'
      - 'traefik.http.services.app.loadbalancer.server.port=3000'

  worker:
    build: .
    command: node worker.js
    labels:
      - 'coolify.managed=true'
      # No traefik labels = not exposed to internet

Health Check Exclusion

Exclude non-HTTP services from Coolify's health monitoring:

services:
  migrations:
    build: .
    command: pnpm db:migrate
    labels:
      - 'exclude_from_hc=true'

  worker:
    build: .
    command: node worker.js
    labels:
      - 'exclude_from_hc=true'

Networking

Each Compose stack deploys to an isolated network named after the resource UUID. Services within the same stack communicate by service name:

services:
  app:
    environment:
      DATABASE_URL: postgres://user:pass@db:5432/myapp
      REDIS_URL: redis://redis:6379

  db:
    image: postgres:16-alpine

  redis:
    image: redis:7-alpine

Cross-Stack Communication

Enable the "Connect to Predefined Network" option to allow services in different stacks to communicate. Reference services using their full name: <service>-<uuid>.

Storage with Compose

Coolify extends Docker Compose with custom storage fields:

services:
  app:
    volumes:
      - data:/app/data

volumes:
  data:
    # Coolify extension: create empty directory
    # is_directory: true

    # Coolify extension: create file with content
    # content: |
    #   key=value
    #   another_key=${ENV_VAR}

Domain and SSL Configuration

Via API

# Set domain (Traefik handles SSL automatically)
curl -s -X PATCH \
  -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"domains": "https://app.example.com"}' \
  "$COOLIFY_URL/api/v1/applications/<uuid>"

# Force HTTPS redirect
curl -s -X PATCH \
  -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"is_force_https_enabled": true}' \
  "$COOLIFY_URL/api/v1/applications/<uuid>"

Wildcard Domains

Configure a wildcard domain on the server level for automatic subdomain routing. Set in Coolify dashboard under Server > Settings > Wildcard Domain.

Troubleshooting

Deployment Strategies

Strategy Comparison

Auto-Deploy

The simplest approach. Coolify redeploys automatically on every push to the configured branch.

Setup

1. Connect repository via GitHub App integration in Coolify dashboard 2. Navigate to application > Advanced > General 3. Enable "Auto Deploy"

Via API

# Enable auto-deploy
curl -s -X PATCH \
  -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"is_auto_deploy_enabled": true}' \
  "$COOLIFY_URL/api/v1/applications/<uuid>"

When to Use

• Development and staging environments
• Projects without a test suite or CI pipeline
• Solo developer workflows
• Rapid prototyping

When NOT to Use

• Production with required test gates
• Multi-environment promotion (dev > staging > prod)
• Teams requiring code review before deploy

Webhook Deploy

Trigger deploys programmatically via HTTP. Gives you control over when deployments happen.

Get the Webhook URL

Each application has a unique deploy webhook URL. Find it in the application's Webhook section in the dashboard, or construct it:

# Deploy via UUID endpoint
curl -s \
  -H "Authorization: Bearer $COOLIFY_TOKEN" \
  "$COOLIFY_URL/api/v1/deploy?uuid=<app-uuid>&force=true"

Webhook Secret (Manual Git Providers)

For non-GitHub App integrations, configure a webhook secret:

1. Generate a random secret string 2. Set it in Coolify's application Webhook settings 3. Configure your Git provider to send push webhooks to Coolify's payload URL with the secret

Coolify only processes webhooks with matching secrets.

GitHub Actions Pipeline

The most controlled approach. Build, test, and scan in CI before triggering Coolify deployment.

Basic: Build and Deploy

name: Deploy to Coolify
on:
  push:
    branches: [main]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v6

      - name: Login to GHCR
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push image
        uses: docker/build-push-action@v6
        with:
          push: true
          tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest

      - name: Deploy to Coolify
        run: |
          curl --fail --request GET \
            '${{ secrets.COOLIFY_WEBHOOK }}' \
            --header 'Authorization: Bearer ${{ secrets.COOLIFY_TOKEN }}'

Required GitHub Secrets

Advanced: Test, Build, Deploy

name: CI/CD Pipeline
on:
  push:
    branches: [main]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm test
      - run: pnpm lint

  build-and-deploy:
    needs: test
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v6

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to GHCR
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          push: true
          tags: |
            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

      - name: Deploy to Coolify
        run: |
          curl --fail --request GET \
            '${{ secrets.COOLIFY_WEBHOOK }}' \
            --header 'Authorization: Bearer ${{ secrets.COOLIFY_TOKEN }}'

Advanced: Update Commit SHA Before Deploy

For pre-built images, update the commit SHA so Coolify pulls the correct version:

- name: Update commit and deploy
  run: |
    # Update the application to use the new commit
    curl --fail -X PATCH \
      -H "Authorization: Bearer ${{ secrets.COOLIFY_TOKEN }}" \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -d '{"git_commit_sha": "${{ github.sha }}"}' \
      "${{ secrets.COOLIFY_URL }}/api/v1/applications/${{ secrets.COOLIFY_APP_UUID }}"

    # Trigger deployment
    curl --fail \
      -H "Authorization: Bearer ${{ secrets.COOLIFY_TOKEN }}" \
      "${{ secrets.COOLIFY_URL }}/api/v1/deploy?uuid=${{ secrets.COOLIFY_APP_UUID }}&force=true"

Manual API Deploy

For production releases where you want full control:

# Deploy specific commit
curl -s -X PATCH \
  -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"git_commit_sha": "abc1234"}' \
  "$COOLIFY_URL/api/v1/applications/<uuid>"

curl -s -H "Authorization: Bearer $COOLIFY_TOKEN" \
  "$COOLIFY_URL/api/v1/deploy?uuid=<uuid>&force=true"

# Rollback to previous commit
curl -s -X PATCH \
  -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"git_commit_sha": "prev-sha"}' \
  "$COOLIFY_URL/api/v1/applications/<uuid>"

curl -s -H "Authorization: Bearer $COOLIFY_TOKEN" \
  "$COOLIFY_URL/api/v1/deploy?uuid=<uuid>&force=true"

Pre/Post Deployment Commands

Run commands before or after deployment:

curl -s -X PATCH \
  -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "pre_deployment_command": "pnpm db:migrate",
    "post_deployment_command": "pnpm db:seed"
  }' \
  "$COOLIFY_URL/api/v1/applications/<uuid>"

Coolify Setup Checklist

1. Enable API access: Settings > Configuration > Advanced > API Access 2. Create API token: Settings > API Tokens (select deploy + needed scopes) 3. Note webhook URL: Application > Webhooks section 4. Add GitHub secrets: COOLIFY_TOKEN and COOLIFY_WEBHOOK 5. Test connection: curl -H "Authorization: Bearer $TOKEN" $URL/api/v1/version