claude-plugins/infraestrutura/skills/easypanel-troubleshoot/SKILL.md

---
name: easypanel-troubleshoot
description: Diagnóstico automático de problemas de deploy no EasyPanel — análise de logs de containers, health endpoints, routing Traefik e recursos para identificar causas raiz.
layer: wiki
---

# EasyPanel Troubleshoot

Diagnóstico automático e inteligente de problemas de deploy no EasyPanel.

## Quando Usar

- Deploy falhou com erros 502/503
- Container em crash loop (restarts frequentes)
- Health endpoint não responde
- Problemas de routing Traefik
- Investigar causa de deploy falhado
- After deploy validation

## Quando NÃO Usar

- Para deploys iniciais (usar `/easypanel-init`)
- Para rollbacks de versão (usar `/easypanel-rollback`)
- Para validação pós-deploy bem-sucedido (usar `/easypanel-validate`)
- Quando o problema é conhecido e a solução já está identificada

## Sintaxe

```bash
/easypanel-troubleshoot <service-name> [--verbose]
```

## Exemplos

```bash
# Diagnóstico básico
/easypanel-troubleshoot dashboard-api

# Diagnóstico detalhado (logs completos)
/easypanel-troubleshoot dashboard-api --verbose
```

## Workflow Automático

### 1. Check Service Status via API

```bash
# Obter token
TOKEN=$(cat /etc/easypanel/.api-token)

# Inspeccionar serviço (estado completo)
curl -s "http://localhost:3000/api/trpc/services.app.inspectService?input=$(echo -n '{"json":{"projectName":"PROJECT","serviceName":"SERVICE"}}' | jq -sRr @uri)" \
  -H "Authorization: Bearer $TOKEN" | jq '.result.data.json'

# Obter logs via API (namespace logs.*, NAO services.app.*)
curl -s "http://localhost:3000/api/trpc/logs.getServiceLogs?input=$(echo -n '{"json":{"projectName":"PROJECT","serviceName":"SERVICE","tail":100}}' | jq -sRr @uri)" \
  -H "Authorization: Bearer $TOKEN"
```

### 2. Fetch Logs (alternativa SSH)
```bash
docker logs <container> --tail 100
```

Parse de erros comuns:
- Port already in use (EADDRINUSE)
- Cannot find module (dependencies)
- Connection refused (database)
- Out of memory (OOM)
- Unhandled promise rejection
- Listen errors

### 3. Check Health Endpoint
```bash
curl https://<domain>/health
```
- Status code: 200, 404, 502, 503?
- Response time
- Response body validation

### 4. Check Traefik Routing
- Traefik labels correctos?
  - router.rule com domain
  - service.loadbalancer.server.port
  - entrypoints=websecure
  - certresolver=letsencrypt
- Domain DNS aponta para servidor?
- SSL certificate válido?

### 5. Check Port Mismatch
- Dockerfile EXPOSE vs app actual port
- docker-compose ports vs Traefik port
- App listening port (from logs)
- Common mismatch: 3000 vs 8080

### 6. Check Environment Variables
- Required vars set? (compare .env.example)
- Sensitive vars (DATABASE_URL, API_KEY)
- Missing vars causing app crash?

### 7. Check Dependencies
- Database reachable? (if applicable)
- Redis reachable? (if applicable)
- External APIs responding?

### 8. Check Resources
- CPU throttling?
- Memory limit reached (OOM)?
- Disk space?

### 9. Generate Report
- Issues found (prioritized: CRITICAL, WARNING, INFO)
- Root cause (if detected)
- Recommended fixes (step-by-step)
- Commands to run

## Error Pattern Detection

### Port Mismatch
```
Pattern: "listening on port X" + Traefik port Y
Fix: Update Dockerfile EXPOSE or Traefik label
```

### Missing Environment Variable
```
Pattern: "is not defined" / "undefined"
Fix: Add variable to EasyPanel environment
```

### Crash Loop
```
Pattern: Restart count > 3 in 10min
Fix: Check logs for root cause
```

### Database Connection
```
Pattern: "ECONNREFUSED" / "Connection refused"
Fix: Verify DATABASE_URL and network connectivity
```

### Memory Issues
```
Pattern: "out of memory" / "OOM killed"
Fix: Increase memory limit in docker-compose
```

## Output Format

```
🔍 EasyPanel Troubleshooting: <service-name>

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 SERVICE STATUS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Container: <name>
Status: Running | Stopped | Restarting
Uptime: <time>
Restarts: <count> (last 10min)
Memory: X / Y MB
CPU: X%

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔴 ISSUES FOUND (X)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. 🔴 CRITICAL: <Issue Title>
   Detected: <details>
   Impact: <what breaks>

   Fix:
   <step-by-step solution>

2. ⚠️  WARNING: <Issue Title>
   ...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 LOGS (Last 20 lines)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[timestamp] INFO: ...
[timestamp] ❌ ERROR: ...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🛠️  RECOMMENDED ACTIONS (Prioritized)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. <Action 1>
2. <Action 2>
3. Redeploy: git commit + push

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔗 HELPFUL RESOURCES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

- Research: /media/ealmeida/Dados/Dev/Docs/EasyPanel-Deploy-Research/
- Checklist: CHECKLIST_EasyPanel_Deploy.md
- Templates: TEMPLATE_Dockerfile_NodeJS_MultiStage
```

## API Endpoints Usados

Ver skill `/easypanel-api` para documentação completa