--- name: coolify-actions description: > This skill should be used when performing operational actions against a Coolify instance using MCP tools — deploying applications, checking deployment status, viewing logs, diagnosing errors, managing environment variables, restarting services, checking server health, or performing any hands-on Coolify management task. Trigger when: "deploy my app", "check Coolify status", "show me Coolify logs", "what's running on Coolify", "restart my app on Coolify", "check server health", "why is my deploy failing", "list my Coolify apps", "add env var to Coolify", "Coolify deployment status", "roll back my deploy", "check my databases", "what resources are on my server". --- # Coolify Actions Operational playbooks for managing a Coolify instance using MCP tools. Each workflow maps a user intent to a specific sequence of `coolify_*` tool calls. > **Requires**: The `coolify` MCP server (bundled with this plugin via `@radoriginllc/coolify-mcp`). Set `COOLIFY_URL` and `COOLIFY_API_TOKEN` environment variables. If MCP tools are not available, fall back to providing the equivalent `curl` commands from the coolify-cicd skill. ## Pre-Flight: Verify Connection Before any workflow, confirm the MCP connection is live: 1. Call `coolify_healthcheck` — expect a "connected" response 2. If it fails, the MCP server is misconfigured or the Coolify instance is unreachable ## Workflow 1: Discover What's Running **Intent**: "What's on my Coolify?", "list my apps", "what resources do I have?" ``` coolify_list_all_resources ``` For more detail on a specific category: - `coolify_list_applications` — all apps with status - `coolify_list_databases` — all databases - `coolify_list_services` — one-click services - `coolify_list_servers` — all managed servers - `coolify_list_projects` — project organization Present results as a summary table: name, status, type, domain. ## Workflow 2: Deploy an Application **Intent**: "deploy my app", "trigger a deployment", "push to production" ``` Step 1: coolify_list_applications → find the app UUID Step 2: coolify_deploy(uuid: "") → trigger deploy, capture deployment_uuid Step 3: coolify_get_deployment(uuid: "") → poll status ``` **Polling pattern**: After triggering deploy, wait 10-15 seconds, then poll `coolify_get_deployment`. Repeat until `status` is `finished`, `failed`, or `cancelled`. Report the result. **Force rebuild** (skip cache): `coolify_deploy(uuid: "", force: true)` **Batch deploy by tag**: `coolify_deploy(tag: "backend")` — deploys all resources with that tag. ## Workflow 3: Check Why a Deployment Failed **Intent**: "why did my deploy fail?", "deployment error", "build failed" ``` Step 1: coolify_list_applications → find app UUID Step 2: coolify_list_deployments(uuid: "", take: 5) → get recent deployments Step 3: coolify_get_deployment(uuid: "") → get full logs ``` Read the `logs` field in the deployment response. Look for: - Build errors (npm, pip, cargo failures) — 5-10 lines before "Build failed" - Missing env vars — `undefined`, `ENOENT`, `KeyError` - Port mismatches — app listening on wrong port - OOM during build — `ENOMEM`, `Killed` If the build succeeded but the app isn't serving, continue to Workflow 5 (diagnose HTTP errors). ## Workflow 4: View Application Logs **Intent**: "show me logs", "what's in the logs?", "check logs for errors" ``` Step 1: coolify_list_applications → find app UUID Step 2: coolify_get_application_logs(uuid: "", lines: 200) ``` Scan for error patterns: `ERROR`, `Error`, `FATAL`, `Unhandled`, stack traces, exit codes. Summarize findings for the user. ## Workflow 5: Diagnose HTTP Errors (502/503/504) **Intent**: "getting a 502", "bad gateway", "site is down", "504 timeout" This is a multi-step diagnostic. Follow the decision tree: ``` Step 1: coolify_list_applications → find app UUID and check status Step 2: coolify_get_application(uuid: "") → check config (port, domain, health check) Step 3: coolify_get_application_logs(uuid: "", lines: 100) → check for crashes Step 4: coolify_list_deployments(uuid: "", take: 3) → check recent deploy status ``` **Decision logic**: - App status is "stopped" or "exited" → offer to restart: `coolify_restart_application` - Port Exposes doesn't match what the app listens on → advise fixing port config - Health check failing → check if health check path returns 200 - Container is OOM-killed → check resource limits in app config - Deploy succeeded but 502 persists → check proxy logs (advise SSH + `docker logs coolify-proxy`) See **coolify-troubleshoot** skill for the full diagnostic decision tree with all edge cases. ## Workflow 6: Manage Environment Variables **Intent**: "add an env var", "update environment variable", "check what env vars are set" **List env vars**: ``` Step 1: coolify_list_applications → find app UUID Step 2: coolify_list_env_vars(uuid: "") ``` **Add a new env var**: ``` coolify_create_env_var( uuid: "", key: "DATABASE_URL", value: "postgresql://...", is_build_time: false ) ``` **Important**: After changing env vars, the app must be redeployed for changes to take effect: ``` coolify_restart_application(uuid: "") ``` **Security reminder**: Never set secrets as build-time variables unless using Docker Build Secrets. See **coolify-security** skill for the decision tree. ## Workflow 7: Check Server Health **Intent**: "how's my server?", "check server health", "is my server okay?" ``` Step 1: coolify_list_servers → list all servers with status Step 2: coolify_get_server(uuid: "") → detailed server info Step 3: coolify_get_server_resources(uuid: "") → all resources on server ``` Report: server reachability, number of running resources, any resource in error/stopped state. For CPU/memory/disk metrics, the Coolify API does not expose Sentinel data — advise checking the dashboard UI at **Servers → Metrics**, or see **coolify-observability** for Grafana/Prometheus setup. ## Workflow 8: Start / Stop / Restart Resources **Intent**: "restart my app", "stop the database", "start the service" **Applications**: `coolify_start_application`, `coolify_stop_application`, `coolify_restart_application` **Databases**: `coolify_start_database`, `coolify_stop_database`, `coolify_restart_database` Always confirm with the user before stopping production resources. ## Workflow 9: Rollback a Deployment **Intent**: "roll back", "revert to previous version", "undo the deploy" ``` Step 1: coolify_list_deployments(uuid: "", take: 10) → find last successful deploy Step 2: Identify the commit SHA or image tag from the last "finished" deployment Step 3: coolify_update_application(uuid: "", settings: {"docker_registry_image_tag": ""}) Step 4: coolify_deploy(uuid: "") ``` **Limitation**: Rollback only works if the previous Docker image still exists locally on the server. Automated Docker cleanup may have pruned it. For git-based apps, rollback by updating the branch or commit reference rather than the image tag. ## Workflow 10: Database Status and Backups **Intent**: "check my databases", "are backups running?", "database status" ``` Step 1: coolify_list_databases → list all databases with status Step 2: coolify_get_database(uuid: "") → detailed config and backup info ``` The API shows database configuration. For triggering manual backups or checking backup history, use the Coolify dashboard — the backup execution API is available at `POST /api/v1/databases/{uuid}/backups`. ## Tool Quick Reference | Intent | Tool | Key Params | |--------|------|------------| | List everything | `coolify_list_all_resources` | — | | Find an app | `coolify_list_applications` | — | | Deploy | `coolify_deploy` | `uuid`, `tag`, `force` | | Check deploy status | `coolify_get_deployment` | `uuid` (deployment UUID) | | View logs | `coolify_get_application_logs` | `uuid`, `lines` | | App details | `coolify_get_application` | `uuid` | | Restart | `coolify_restart_application` | `uuid` | | Env vars | `coolify_list_env_vars` | `uuid` | | Add env var | `coolify_create_env_var` | `uuid`, `key`, `value`, `is_build_time` | | Update app config | `coolify_update_application` | `uuid`, `settings` | | Server health | `coolify_get_server` | `uuid` | | Server resources | `coolify_get_server_resources` | `uuid` | ## Anti-Patterns | Anti-Pattern | Consequence | |-------------|-------------| | Deploying without checking current status first | May deploy over a running debug session or ongoing rollback | | Polling deployment status in a tight loop (< 5 seconds) | Overloads Coolify's database; use 10-15 second intervals | | Restarting apps to "fix" problems without checking logs first | Masks the root cause; problem recurs on next deploy | | Adding env vars without redeploying | Changes don't take effect until restart/redeploy | | Stopping a database without checking which apps depend on it | Apps crash with connection errors | | Using `force: true` on every deploy | Defeats build caching; 3-10x slower builds for no benefit | ## Related Skills - **coolify-deploy** — Build pack selection, deployment configuration, registry patterns - **coolify-cicd** — API reference, GitHub Actions, webhook setup - **coolify-troubleshoot** — Full diagnostic decision trees for HTTP errors, build failures, SSL issues - **coolify-security** — Environment variable security, build secrets - **coolify-databases** — Database provisioning, backup configuration - **coolify-observability** — Monitoring, log drains, alerting setup ## Additional Resources ### Reference Files - **`references/workflow-recipes.md`** — Extended workflows: bulk operations, multi-app coordination, automated health checks