coolify-manager

What this skill does

# Coolify Manager

## Overview

This skill enables management of Coolify deployments through both the official CLI and direct API access. It provides workflows for diagnosing service issues, fixing common WordPress problems, managing containers, and performing deployment operations across self-hosted and cloud Coolify instances.

## Quick Start

### Prerequisites Check

Before proceeding, verify:
1. User has access to a Coolify instance (self-hosted or cloud)
2. User can obtain an API token from their Coolify dashboard at `/security/api-tokens`
3. User knows their Coolify instance URL

### When to Use This Skill

Invoke this skill when the user:
- Mentions Coolify by name
- Needs to debug a down WordPress site hosted on Coolify
- Wants to check service health, logs, or status
- Needs to access a container terminal
- Wants to manage deployments, services, or applications
- Has SSL certificate issues on Coolify-hosted sites
- Needs to fix .htaccess or PHP configuration issues
- Wants to manage environment variables or configurations

## Installation & Setup

### Step 1: Install Coolify CLI

If the CLI is not already installed, use the bundled installation script:

```bash
bash scripts/install_coolify_cli.sh
```

This installs to `~/.local/bin/coolify`. Ensure this directory is in the user's PATH:

```bash
export PATH="$HOME/.local/bin:$PATH"
```

Add this line to the user's shell configuration file (`~/.bashrc`, `~/.zshrc`, etc.) for persistence.

### Step 2: Configure Context

Add the user's Coolify instance:

```bash
coolify context add <context-name> <coolify-url> <api-token>
```

Example:
```bash
coolify context add production https://coolify.example.com YOUR_API_TOKEN
```

### Step 3: Verify Connection

```bash
coolify context verify
```

This confirms successful authentication and connectivity.

### Health Check

Run the bundled health check script:

```bash
bash scripts/check_health.sh
```

This displays:
- CLI version
- Configured contexts
- Connection status
- Available resources
- Server status

## Diagnosing Issues

### Workflow Decision Tree

When a user reports an issue:

1. **Is it service availability?**
   - Site is down → Check service status
   - Container not responding → Check logs
   - Deploy failed → Check deployment history

2. **Is it WordPress-specific?**
   - 500 error after .htaccess change → Fix .htaccess
   - REST API warnings → Diagnose REST API
   - PHP limits → Update PHP configuration
   - SSL issues → Check certificates

3. **Is it performance/configuration?**
   - Need to change env vars → Manage environment
   - Need to scale → Manage resources
   - Need to deploy → Trigger deployment

### Check Service Status

```bash
# List all resources with status
coolify resource list

# Get detailed service info
coolify service get SERVICE_UUID

# Check specific application
coolify app get APP_UUID
```

Status indicators:
- `running:healthy` - Service is operational
- `running:unhealthy` - Service has issues (check logs)
- `stopped` - Service is not running
- `deploying` - Deployment in progress

### Check Logs

```bash
# Application logs
coolify app logs APP_UUID

# Get more lines
coolify app logs APP_UUID --lines 500
```

For services with multiple components (like WordPress with database), get the service details first to identify component UUIDs:

```bash
coolify service get SERVICE_UUID --format json
```

Then extract application/database UUIDs from the JSON output.

### Using the API Directly

When CLI doesn't provide needed functionality, use direct API calls. Reference: `references/api_endpoints.md`

Example - Get detailed service configuration:
```bash
curl -H "Authorization: Bearer API_TOKEN" \
  https://coolify-instance.com/api/v1/services/SERVICE_UUID
```

## Managing Services

### Start/Stop/Restart

```bash
# Services
coolify service start SERVICE_UUID
coolify service stop SERVICE_UUID
coolify service restart SERVICE_UUID

# Applications
coolify app start APP_UUID
coolify app stop APP_UUID
coolify app restart APP_UUID

# Databases
coolify database start DB_UUID
coolify database stop DB_UUID
coolify database restart DB_UUID
```

### Deploy Applications

```bash
# Deploy by UUID
coolify deploy APP_UUID

# Check deployment status
coolify deploy list APP_UUID
```

### Manage Environment Variables

```bash
# List env vars
coolify app env list APP_UUID

# Add/update env var
coolify app env set APP_UUID VAR_NAME "value"

# Delete env var
coolify app env delete APP_UUID VAR_NAME

# Restart to apply changes
coolify app restart APP_UUID
```

## WordPress Troubleshooting

For WordPress-specific issues, reference: `references/wordpress_fixes.md`

### Accessing WordPress Container

**Via Coolify Web Terminal** (Recommended):
1. Navigate to Coolify dashboard
2. Go to WordPress service
3. Click "Terminal" in sidebar
4. Select "wordpress" container

**Via Docker** (if SSH access available):
```bash
docker exec -it CONTAINER_NAME bash
```

WordPress files are located at: `/var/www/html/`

### Common WordPress Issues

#### Site Down After .htaccess Edit

This is a critical issue that requires immediate action:

1. Access the container terminal (see above)
2. Check the .htaccess file:
   ```bash
   cd /var/www/html
   cat .htaccess
   ```
3. Identify problematic line (usually last added line)
4. Remove problematic line:
   ```bash
   sed -i '$d' /var/www/html/.htaccess
   ```
5. Service should recover immediately

#### PHP Configuration Limits

To increase PHP limits (max_input_vars, upload limits, etc.):

**Correct syntax** (no `=` sign, use space):
```bash
echo "php_value max_input_vars 3000" >> /var/www/html/.htaccess
echo "php_value upload_max_filesize 64M" >> /var/www/html/.htaccess
echo "php_value post_max_size 128M" >> /var/www/html/.htaccess
echo "php_value memory_limit 256M" >> /var/www/html/.htaccess
```

Verify:
```bash
tail -5 /var/www/html/.htaccess
```

#### REST API False Positives

If Site Health reports REST API unavailable but the site works normally:

1. Test REST API externally:
   ```bash
   curl https://site.com/wp-json/
   ```

2. If JSON returns, it's a **false positive** - the API works fine

3. Common cause: Site Health loopback test is blocked, not the actual API

4. Verify HTTP_AUTHORIZATION in .htaccess:
   ```bash
   grep "HTTP_AUTHORIZATION" /var/www/html/.htaccess
   ```

   Should contain:
   ```
   RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
   ```

For detailed WordPress troubleshooting steps, load `references/wordpress_fixes.md` into context.

### SSL Certificate Issues

Check certificate status:
```bash
echo | openssl s_client -servername domain.com -connect domain.com:443 2>/dev/null | openssl x509 -noout -dates -subject -issuer
```

Coolify uses Traefik with Let's Encrypt for automatic SSL. Certificates auto-renew before expiration.

If certificate is invalid:
1. Check Coolify dashboard → Service → Domains
2. Regenerate SSL certificate
3. Verify Traefik labels in service configuration

## Advanced Operations

### Working with Multiple Contexts

Switch between Coolify instances:

```bash
# List contexts
coolify context list

# Switch context
coolify context use staging

# Perform operations
coolify deploy APP_UUID

# Switch back
coolify context use production
```

### Batch Operations with JSON Output

Use `--format json` with tools like `jq`:

```bash
# Get all unhealthy services
coolify resource list --format json | jq '.[] | select(.status | contains("unhealthy"))'

# Get all running applications
coolify resource list --format json | jq '.[] | select(.type=="application" and .status=="running")'

# Extract service UUIDs
coolify service list --format json | jq -r '.[].uuid'
```

### Server Management

```bash
# List servers with IPs/ports
coolify server list -s

# Validate server connection
coolify server validate SERVER_UUID

# Get server domains
coolify server domains SERVER_UUID
```

### Backup and Recovery

```bash
# List databases
coolify database list

# Backup datab