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)

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