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

name, description, disable-model-invocation

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

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] ✅ Container started
[03:50] ❌ Health check 1/5: 502 Bad Gateway
[04:00] ❌ Health check 2/5: 502 Bad Gateway
[04:10] ❌ Health check 3/5: 502 Bad Gateway
[04:20] ❌ HEALTH CHECK FAILED (3/5 retries)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔴 ERROR DETAILS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Issue: Health endpoint not responding (502)
Likely cause: Port mismatch or app crash

Logs (last 20 lines):
  > Error: listen EADDRINUSE: address already in use :::8080
  > at Server.setupListenHandle [as _listen2]

Root cause detected: App listening on port 8080, Traefik expects 3000

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔄 AUTO-ROLLBACK
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[04:25] ⏪ Rolling back to previous version (commit: 7d3a1f2)
[04:30] ✅ Rollback complete
[04:35] ✅ Health check: 200 OK (service restored)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🛠️  RECOMMENDED FIXES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. Update Dockerfile EXPOSE: Change 8080 → 3000
   OR
2. Update docker-compose.yml Traefik label:
   traefik.http.services.X.loadbalancer.server.port=8080

3. Test fix locally: docker build && docker run
4. Commit fix + redeploy: /easypanel-deploy

🔍 Troubleshooting:
   /easypanel-troubleshoot <service-name>

Auto-Rollback Logic

Trigger Conditions:

• Health check fails 3/5 times
• Container crashes dentro de 60s
• Metrics críticos (CPU > 95%, Memory OOM)

Rollback Actions:

1. Identificar último commit estável (health OK)
2. git revert ou git checkout
3. Force push para trigger redeploy
4. Aguardar health check OK
5. Report success/fail

Flags

--skip-tests

/easypanel-deploy --skip-tests

Quando usar:

• CI/CD já executou tests
• Tests demoram muito (>5min)
• Deploy de hotfix urgente

--force

/easypanel-deploy --force

Quando usar:

• Ignorar validation warnings
• Deploy apesar de score < 7/10
• Override safety checks

⚠️ ATENÇÃO: Usar apenas se souber o que está a fazer.

Integration com CI/CD

# .gitea/workflows/deploy.yml
steps:
  - name: Deploy
    run: |
      /easypanel-deploy --skip-tests
    env:
      EASYPANEL_TOKEN: ${{ secrets.EASYPANEL_TOKEN }}

API Endpoints Usados

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

Acção	Endpoint
Deploy serviço	POST services.app.deployService
Redeploy	POST services.app.redeployService
Estado serviço	GET services.app.inspectService
Logs	GET services.app.getServiceLogs

MCPs Necessários

• ✅ ssh-unified - Acesso ao servidor para executar comandos API
• ✅ gitea - Git operations e push

Tools Necessários

# Git
git status
git add .
git commit
git push

# Docker
docker build
docker stats

# Curl
curl -f https://domain/health

Metrics Tracking

Após deploy, gravar métricas:

INSERT INTO tblskill_metrics (
  skill_name, duration_ms, success,
  build_time_ms, image_size_mb, deploy_time_ms,
  health_check_status, cpu_avg, ram_mb
) VALUES (
  '/easypanel-deploy', DURATION, SUCCESS,
  BUILD_TIME, IMAGE_SIZE, DEPLOY_TIME,
  'ok', CPU, RAM
);

Checklist Execução

• Executar /easypanel-validate
• Check score >= 7/10
• Run tests (se não --skip-tests)
• Build local test
• Verificar uncommitted changes
• Push to Gitea
• Monitor build EasyPanel
• Health check (5 retries)
• Validate metrics (CPU, RAM)
• Report success ou trigger rollback
• Log metrics

---

Versão: 1.0.0 | Autor: Descomplicar® | Data: 2026-02-04

Metadata (Desk CRM Task #65)

Tarefa: SKL: /easypanel-deploy - Automated Deploy + Validation
Milestone: 294 (Skills Claude Code)
Tags: skill(79), stackworkflow(75), claude-code(81), activo(116)
Responsáveis: Emanuel(1), AikTop(25)
Status: 4 (Em progresso) → 5 (Concluído)

---

/ @author Descomplicar® | @link descomplicar.pt | @copyright 2026 **/