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

name, description, disable-model-invocation, layer

name	description	disable-model-invocation	layer
easypanel-deploy	Deploy completo e automatizado para EasyPanel com validação integrada, monitoring e safety net (auto-rollback) via API oficial.	true	wiki

EasyPanel Deploy

Deploy completo e automatizado para EasyPanel com validação integrada.

Quando Usar

• Deploy completo de projecto
• Deploy com validação automática
• Deploy com monitoring
• Deploy com safety net (auto-rollback)
• Production deploys críticos

Sintaxe

/easypanel-deploy [--skip-tests] [--force]

Exemplos

# Deploy normal (com tests e validation)
/easypanel-deploy

# Deploy sem tests (CI/CD já rodou)
/easypanel-deploy --skip-tests

# Force deploy (ignorar warnings)
/easypanel-deploy --force

Workflow Completo (9 Steps)

1. Pre-deploy Validation

/easypanel-validate

Gates:

• Score < 7/10 → ABORT (excepto --force)
• Critical issues → ABORT
• Se pass → Continue

2. Run Tests (se não --skip-tests)

npm test

Gates:

• Tests fail → ABORT
• No tests found → WARNING (continue)
• Tests pass → Continue

3. Build Local (test)

docker build --no-cache -t <project>:test .

Checks:

• Build completa sem erros
• Image size < 200MB (Node.js)
• EXPOSE port correcto

Gates:

• Build fail → ABORT
• Image size > 500MB → WARNING (continue com --force)

4. Git Check

git status

Checks:

• Uncommitted changes?
• Untracked files?

Actions:

• Se changes → PROMPT: "Commit agora? [y/N]"
• Se yes → git add . && git commit -m "deploy: ..."
• Se no → ABORT

5. Push to Gitea

git push origin main

Actions:

• Push commits
• Se CI/CD configurado → Aguardar webhook trigger
• Log commit SHA

6. Monitor EasyPanel Deploy

Via API (preferido - sincroniza com GUI):

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

# Verificar estado do serviço
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"

# Listar todos os serviços do projecto
curl -s "http://localhost:3000/api/trpc/projects.inspectProject?input=$(echo -n '{"json":{"projectName":"PROJECT"}}' | jq -sRr @uri)" \
  -H "Authorization: Bearer $TOKEN"

Via SSH (fallback):

# Poll cada 10s (timeout 5min)
docker service ls | grep <service>
docker service ps <service>

Timeline:

• [00:00] Build started
• [01:30] Build complete
• [02:00] Container starting
• [02:15] Health check iniciado

7. Health Check (retry 5x, interval 10s)

curl -f https://<domain>/health

Retry Logic:

• Tentativa 1-5: aguardar 10s entre cada
• Se 200 OK → SUCCESS
• Se 5xx após 5 retries → ROLLBACK
• Se timeout → ROLLBACK

8. Metrics Validation

# Via docker stats ou EasyPanel API
docker stats <container> --no-stream

Checks:

• CPU < 80% (avg 60s)
• Memory < 80% limit
• No errors em logs (últimos 60s)

Gates:

• CPU > 90% → WARNING (potential issue)
• Memory > 90% → WARNING (OOM risk)
• Errors em logs → WARNING + report

9. Success Report

Output:

• Total deploy time
• Build time
• Image size
• Health status
• Metrics snapshot
• URLs (production, health, logs)

Output Format (Success)

🚀 EasyPanel Deploy: <project-name>

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⏱️  TIMELINE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[00:00] ✅ Pre-deploy validation (score: 9.2/10)
[00:15] ✅ Tests passed (12/12, 2.3s)
[00:20] ✅ Local build (82MB, 1m 34s)
[00:25] ✅ Git push (commit: a3f5c21)
[01:55] ✅ EasyPanel build started
[03:42] ✅ Container started (dashboard-api-6f9d8)
[03:50] ✅ Health check 1/5: 200 OK
[03:52] ✅ Health check 5/5: 200 OK (stable)
[04:00] ✅ Metrics validated (CPU: 12%, RAM: 45MB/512MB)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ DEPLOY SUCCESS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 Metrics:
   - Total time: 4m 0s (vs ~60min manual, -93%)
   - Build time: 1m 34s
   - Image size: 82MB (-80% vs non-multi-stage)
   - Cold start: 2.1s
   - Memory usage: 45MB / 512MB (8.8%)
   - CPU usage: 12% (avg first 60s)

🌐 Endpoints:
   - Production: https://domain.descomplicar.pt
   - Health: https://domain.descomplicar.pt/health

📋 Logs:
   - EasyPanel: https://easy.descomplicar.pt/services/<service>/logs
   - Gitea: https://git.descomplicar.pt/org/repo/actions

🔔 Next Steps:
   1. Monitor uptime (first 24h critical)
   2. Check error rate (should be <1%)
   3. Load testing (optional, recommended)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Output Format (Failed)

❌ DEPLOY FAILED

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⏱️  TIMELINE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[00:00] ✅ Pre-deploy validation
[00:15] ✅ Tests passed
[00:20] ✅ Local build
[00:25] ✅ Git push
[01:55] ✅ EasyPanel build started
[03:42]