Coolify Deploy

intent

deploy and manage applications on Coolify infrastructure using the official CLI. use this skill when creating new apps from GitHub repos, redeploying after code changes, managing environment variables, or debugging unhealthy deployments. the CLI-first approach keeps deployments visible in the Coolify UI and enables push-to-deploy automation. fall back to direct Docker/Traefik only if Coolify app creation is blocked.

inputs

Coolify CLI context

• coolify command installed and on PATH
• authenticated to Coolify server (verify with coolify context verify)
• server and project UUIDs from your Coolify instance

Application metadata

• server_uuid: Coolify server identifier
• project_uuid: Coolify project identifier
• environment_name: deployment target, usually production
• app_name: human-readable app identifier
• git_repository: owner/repo format (e.g. acme/myapp)
• git_branch: branch to deploy, typically main
• build_pack: build strategy, typically dockerfile
• ports_exposes: container port to expose, typically 80
• domains: public domain(s) for the app (e.g. http://myapp.1.2.3.4.sslip.io)

GitHub integration (private repos only)

• github_app_uuid: UUID of configured GitHub App in Coolify (get from coolify github list --format=json)
• GitHub App must have read access to the target private repository

External connection: Coolify Server

• endpoint: your Coolify instance hostname or IP
• auth: configured via coolify CLI context (SSH key or token)
• edge case: rate limits on API calls; add 2-3 second delays between sequential commands if hitting 429 responses

External connection: GitHub (for private repos)

• auth: GitHub App OAuth token, managed by Coolify
• edge case: token expiry or revoked access causes app create github to fail silently; verify app UUID with coolify github list
• edge case: if repo is private and GitHub App lacks read permission, creation will fail with auth error

procedure

step 1: verify CLI and list available contexts

input: Coolify CLI installed, authenticated context

procedure: run context verification and list available GitHub apps and existing apps.

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

output: JSON output confirming active context, available GitHub Apps with UUIDs, and existing apps. if context fails, stop and reconfigure auth.

edge cases: if coolify command not found, install from official docs. if context verify fails, Coolify server is unreachable or credentials are stale.

step 2: create app from GitHub repository

input: verified context, server_uuid, project_uuid, github_app_uuid (if private repo), git_repository, git_branch, app_name, domains, ports_exposes

procedure: invoke CLI to create new app. use app create github for private repos (supply github_app_uuid). use app create public only for public GitHub repos to avoid GitHub App dependency.

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 <branch> \
  --build-pack dockerfile \
  --ports-exposes <port> \
  --name <app_name> \
  --domains <domain> \
  --instant-deploy \
  --format=json

output: JSON response containing app_uuid, status (typically pending or queued), and deployment metadata. capture app_uuid for subsequent commands.

edge cases: if app creation returns status failed with auth error, verify github_app_uuid exists and has read permission on repo. if CLI hangs for >30s, Coolify API is slow or unreachable; retry with timeout flag. if creation succeeds but returns no app_uuid in response, API response format changed; check CLI version compatibility.

step 3: add or update environment variables

input: app_uuid from step 2, environment variable name and value (e.g. PORT=80, NODE_ENV=production)

procedure: create or update env vars one at a time. common vars: PORT (required for nginx templating), NODE_ENV, DATABASE_URL.

coolify app env create <app_uuid> --key <KEY> --value <VALUE> --format=json

output: JSON response confirming env var created with key, value, and timestamp.

edge cases: if env var update returns not found error, app_uuid is invalid or app not yet fully provisioned; wait 10-15s and retry. if nginx template expects ${PORT} but var not set, deployment will fail with templating error.

step 4: force redeploy (if needed)

input: app_uuid, optionally git_branch override

procedure: trigger immediate redeployment. use --force to bypass cache. useful after env var changes or to retry after transient failures.

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

output: JSON response with new deployment UUID and status (queued, building, etc.).

edge cases: if force redeploy returns app currently deploying error, wait 30-60s for current deploy to finish before retrying. if redeploy starts but immediately moves to exited:unhealthy, check logs in step 5.

step 5: verify deployment success

input: app_uuid, deployed domain

procedure: check both Coolify app status and HTTP connectivity. pull latest deployment logs if status is not healthy.

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

output: app status JSON (check statuses.main field for health), deployment list JSON showing completed deployments, deployment logs (raw text), HTTP response code from curl (expect 200 or 3xx redirect).

edge cases: if curl -I returns connection refused, app container may not be listening on exposed port or Traefik routing not yet configured. wait 10-20s and retry. if app status shows running:unknown but curl returns 200, treat as success (Coolify status may lag). if logs show build failed or container exited, review build errors below in decision points.

decision points

if private GitHub repo: use app create github with --github-app-uuid <uuid>. get UUID from coolify github list --format=json. if UUID is wrong or GitHub App lacks permission, creation will fail with auth error. verify app UUID and repo access before retrying.

if public GitHub repo: optionally use app create public (no GitHub App UUID needed). if public creation fails but private creation works, repo may have changed to private.

if app status is exited:unhealthy or exited:error: check deployment logs via coolify app deployments logs <app_uuid>. common causes:

• wrong Dockerfile path or missing Dockerfile in repo: verify build-pack is correct
• missing required env vars (e.g. PORT, DATABASE_URL): add via step 3
• runtime error (node modules not installed, syntax error, missing dependency): check build logs for npm/yarn/build step failures
• port mismatch: app listens on port X but --ports-exposes specifies port Y; add env var PORT=Y and redeploy

if app uses Vite, Rollup, or native modules and build fails on Alpine: use Debian-based Node image (node:20-slim instead of node:20-alpine). Alpine lacks libc and build tools needed for native modules. update Dockerfile and redeploy.

if nginx template error (${PORT} not substituted): env var PORT is not set. run step 3 with --key PORT --value <port> (typically 80 or 3000) and force redeploy (step 4).

if domain responds with HTTP 200 but Coolify UI still shows running:unknown: UI status may lag or reflect a transient state during initialization. treat successful HTTP response + finished deployment as success. if domain returns error (5xx, timeout), check app logs.

if CLI command times out or returns network error: Coolify API is slow or unreachable. wait 30s and retry. if persistent, check Coolify server status and network connectivity.

if no Coolify CLI-managed app creation is possible (e.g. server is down, quota exceeded): fallback to direct Docker + Traefik routing. see references/coolify-api.md for direct API patterns. this approach will not appear in Coolify UI and does not support push-to-deploy.

output contract

successful app creation: JSON response with fields:

• app_uuid: string, used for all subsequent commands
• name: string, matches --name input
• status: string, one of pending, queued, building, running
• domains: array of strings, public access URLs

successful deployment: JSON response with fields:

• deployment_uuid: string
• status: string, one of queued, building, running, exited:success, exited:error, exited:unhealthy
• created_at: ISO timestamp

successful verification: all of:

• app status JSON shows status: "running" or statuses.main: "running"
• deployment list shows at least one entry with status exited:success
• curl -I <domain> returns HTTP 200, 301, or 302 (not 5xx, not connection refused)
• logs contain no ERROR or FAILED entries in final 20 lines

env var creation: JSON response with fields:

• key: string
• value: string
• created_at: ISO timestamp

all commands use --format=json to ensure parseable output. raw text output (logs, curl) is human-readable but not JSON.

outcome signal

• user can curl the deployed domain and get HTTP 200 response
• app appears in Coolify UI with status running
• deployment list shows a completed deployment with exited:success status
• logs contain no final error messages
• if env vars were added, they appear in app settings UI
• if redeploy was forced, a new deployment entry appears in deployment history
• subsequent git pushes to the configured branch trigger automatic redeploys (if push-to-deploy is enabled in Coolify UI)

failed outcome: domain returns connection error, 5xx status, or timeout; app status is exited:error or exited:unhealthy; logs show build or runtime errors; commands return auth or timeout errors.