coolify-deployment

name	coolify-deployment
description	Deploys applications, databases, and services on self-hosted Coolify instances, manages environments and env vars, runs infrastructure diagnostics, and performs batch operations. Use when deploying apps to Coolify, managing Coolify servers, debugging deployment issues, setting up databases, or managing Coolify infrastructure.

Coolify Deployment

Topic Routing

Read the matching reference before working on any of these topics:

Topic	Reference
Application deployment	references/applications.md
Database & service management	references/databases-services.md
Infrastructure & diagnostics	references/infrastructure.md
Docker Compose templates	references/docker-compose.md
CI/CD & Docker image deploys	references/ci-cd-webhooks.md

Critical Rules

Project Structure

• Coolify organizes resources as: Server → Project → Environment → Resources (apps, databases, services)
• Always start with get_infrastructure_overview to understand the current state before making changes
• Use projects tool with action params (list, get, create) — one tool, multiple operations

Application Deployment

• Deploy from public repos, private GitHub repos (via GitHub App), SSH keys, or Docker images
• Configure health checks (path, interval, retries) during application create to avoid unhealthy deployments
• Use deploy with force_rebuild: true only when cache issues are suspected — normal deploys are faster
• Check deployment status with deployment action list_for_app after triggering a deploy

Diagnostics

• diagnose_app accepts name or domain (e.g., "my-app" or "example.com") — not just UUIDs
• diagnose_server accepts name or IP address — use for connectivity and resource issues
• find_issues scans all infrastructure — use as a health check before and after changes

Environment Variables

• Use env_vars tool with resource: "application" or resource: "service" — supports list, create, update, delete
• bulk_env_update updates a variable across multiple apps at once — use for shared config like API URLs
• Env vars require app restart to take effect — use control with action: "restart" after updates

Database Management

• Supports 8 database types: PostgreSQL, MySQL, MariaDB, MongoDB, Redis, KeyDB, ClickHouse, Dragonfly
• Configure backup schedules via database_backups with action: "create" — set frequency and retention
• Backups can target S3-compatible storage — configure via backup schedule creation

Security

• Store COOLIFY_ACCESS_TOKEN in .env — never commit to source control
• Private keys for SSH deployments: manage via private_keys tool, never hardcode
• Use validate_server to verify SSH connectivity before deploying

Docker Compose

• Coolify supports two compose modes: Raw (paste YAML, no build:) and Repository (git URL, full features)
• Use magic variables (SERVICE_PASSWORD_*, SERVICE_URL_*) for auto-generated credentials and proxy URLs — never hardcode
• Remove ports: for proxied services — Traefik handles routing via SERVICE_URL_NAME_PORT

CI/CD Integration

• Trigger deploys via webhook with tag or UUID — use for automated pipelines
• Docker image deployments (create_dockerimage) skip the build step — use for pre-built images from registries

Workflow: Deploy Application

1. Survey — get_infrastructure_overview → identify target server and project
2. Create project (if needed) — projects action create with name and description
3. Create environment — environments action create in the target project
4. Deploy — application action create_public (or create_github / create_dockerimage) with health check config
5. Verify — deployment action list_for_app → wait for finished status; if failed → application_logs → fix → redeploy
6. Set env vars — env_vars resource application action create → control action restart
7. Validate — diagnose_app by name → confirm status running and health check passing

Workflow: Diagnose & Fix

1. Scan — find_issues → list all unhealthy resources
2. Investigate — diagnose_app or diagnose_server with name/domain/IP
3. Check logs — application_logs for the affected app
4. Fix — update config, env vars, or redeploy as needed
5. Restart — control resource application action restart
6. Verify — diagnose_app again → confirm status running

Deployment Failure Recovery

Deploy failed → check status
├── Health check failing → verify health check path returns 200 → fix app → redeploy
├── Build error → application_logs → fix Dockerfile/build config → deploy with force_rebuild
├── Port conflict → check server_resources → update port mapping → redeploy
├── SSH key invalid → validate_server → private_keys action update → retry
└── Out of resources → server diagnostics → scale server or stop unused apps

Deploy Public Repo — Full Example

# 1. Create app from public repo
application(
  action="create_public",
  project_uuid="proj-abc",
  environment_name="production",
  server_uuid="srv-xyz",
  repository_url="https://github.com/org/my-app",
  branch="main",
  build_pack="dockerfile",
  health_check_path="/health",
  health_check_interval=30,
  health_check_retries=3
)
# → returns { uuid: "app-123", status: "deploying" }

# 2. Set env vars
env_vars(resource="application", action="create", uuid="app-123", key="DATABASE_URL", value="postgres://...", is_preview=false)

# 3. Restart to pick up env vars
control(resource="application", action="restart", uuid="app-123")

# 4. Verify
diagnose_app(identifier="my-app")
# → status: "running", health_check: "healthy"

MCP Config (VS Code)

{
  "servers": {
    "Coolify": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@masonator/coolify-mcp"],
      "envFile": "${workspaceFolder}/.env"
    }
  }
}