Coolify Deploy

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.

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