name: coolify-deploy
description: Create, deploy, update, and troubleshoot Coolify applications with the official Coolify CLI. Use when user wants deploy via Coolify, app creation from GitHub, redeploy on push, env vars, logs, or fallback Docker/Traefik routing.

Coolify Deploy

Use the official coolify CLI first. Use direct Docker + Traefik only as fallback.

Core Rules

1. Prefer CLI-managed apps so deployments appear in Coolify UI and support push-to-deploy.
2. Use app create github for private GitHub repos and the correct GitHub App UUID.
3. Verify both app status and HTTP 200 before calling a deploy finished.
4. Use direct Docker only if Coolify creation is blocked.

When to Use

• Creating a new Coolify app
• Redeploying after code changes
• Debugging unhealthy deployments
• Adding env vars or checking deployment logs

Required Info

• server_uuid
• project_uuid
• environment_name (usually production)
• github_app_uuid for private repos
• repo, branch, domain, exposed port

Preferred Workflow

1. Verify CLI + context

coolify context verify
coolify github list --format=json
coolify app list --format=json

2. Create app from private GitHub repo

coolify app create github \
  --server-uuid <server_uuid> \
  --project-uuid <project_uuid> \
  --environment-name production \
  --github-app-uuid <github_app_uuid> \
  --git-repository owner/repo \
  --git-branch main \
  --build-pack dockerfile \
  --ports-exposes 80 \
  --name <app-name> \
  --domains http://<app>.<ip>.sslip.io \
  --instant-deploy \
  --format=json

3. Add env vars when needed

coolify app env create <app-uuid> --key PORT --value 80 --format=json

4. Force redeploy

coolify deploy uuid <app-uuid> --force --format=json

5. Verify success

coolify app get <app-uuid> --format=json
coolify app deployments list <app-uuid> --format=json
curl -I http://<domain>

GitHub App Integration

List configured GitHub apps:

coolify github list --format=json

Use the UUID from this output in coolify app create github --github-app-uuid ....

If a repo is private and public creation fails, switch to github creation.

Common Issues

App is exited:unhealthy

Check deployment logs first:

coolify app deployments list <app-uuid> --format=json
coolify app deployments logs <app-uuid>

Then verify:

• wrong GitHub App UUID
• wrong Dockerfile path
• missing env vars like PORT
• build/runtime errors

Vite/Rollup native module error

Use Debian-based Node image:

FROM node:20-slim AS builder

Avoid Alpine for builds that need native Rollup modules.

nginx template expects ${PORT}

Set env var in Coolify:

coolify app env create <app-uuid> --key PORT --value 80 --format=json

Domain responds but UI still says running:unknown

Treat HTTP 200 + finished deployment as success. Coolify may still show running:unknown.

Fallback: Direct Docker Deploy

Only use when CLI-managed app creation is blocked.
See references/coolify-api.md for direct Docker/Traefik fallback patterns.

Quick Reference

coolify github list --format=json
coolify app create github --server-uuid <server> --project-uuid <project> --environment-name production --github-app-uuid <ghapp> --git-repository owner/repo --git-branch main --build-pack dockerfile --ports-exposes 80 --name myapp --domains http://myapp.<ip>.sslip.io --instant-deploy --format=json
coolify app env create <uuid> --key PORT --value 80 --format=json
coolify deploy uuid <uuid> --force --format=json
coolify app deployments list <uuid> --format=json
curl -I http://myapp.<ip>.sslip.io