etylsarin/coolify-deployment

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"
    }
  }
}