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

name, description, disable-model-invocation, layer

name	description	disable-model-invocation	layer
easypanel-rollback	Rollback seguro de deployments EasyPanel para versões anteriores estáveis via API oficial.	true	wiki

EasyPanel Rollback

Rollback rápido e seguro para versões anteriores estáveis.

Quando Usar

• Deploy falhou (health checks fail)
• Aplicação com erros em produção
• Rollback urgente necessário
• Testar versão anterior
• Recovery após incidente

Sintaxe

/easypanel-rollback <service-name> [--to-version <version>] [--auto]

Exemplos

# Rollback para versão anterior imediata
/easypanel-rollback dashboard-api

# Rollback para tag específica
/easypanel-rollback dashboard-api --to-version v1.2.5

# Rollback automático (sem confirmação)
/easypanel-rollback dashboard-api --auto

Workflow Completo

1. List Recent Versions

git log --oneline -n 10
git tag --sort=-creatordate | head -n 10

Output:

v1.3.0 (current) ❌ FAILING - Health: 502
v1.2.5 (previous) ✅ STABLE - Health: 200 OK, Uptime: 99.8%
v1.2.4 ✅ STABLE
v1.2.3 ✅ STABLE

Metadata tracking:

• Commit SHA
• Deploy timestamp
• Health status (last known)
• Uptime percentage (if tracked)
• Issue description (se falhou)

2. Select Target Version

Strategies:

A. Interactive (default)

➜ Rollback to: [2] v1.2.5 (recommended)

Available versions:
1. v1.3.0 (current) ❌ FAILING
2. v1.2.5 (previous) ✅ STABLE (recommended)
3. v1.2.4 ✅ STABLE
4. v1.2.3 ✅ STABLE

Enter number [2]:

B. Automatic (--auto)

Last known good: v1.2.5 (health OK, deployed 2h ago)
Auto-selecting v1.2.5...

C. Specific (--to-version)

Target version specified: v1.2.5
Validating...

3. Confirm Rollback (se não --auto)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 ROLLBACK PLAN
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Current: v1.3.0 (a3f5c21) - Port mismatch issue
Target:  v1.2.5 (7d3a1f2) - Stable, 99.8% uptime

Changes (diff):
  - src/server.ts: PORT 8080 → 3000
  - docker-compose.yml: Traefik port fix
  + Reverts 3 commits

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

Confirm rollback? [Y/n]:

4. Perform Rollback

Method A: Git Revert (small rollback, 1-3 commits)

git revert --no-commit a3f5c21..HEAD
git commit -m "revert: rollback to v1.2.5 due to port mismatch"

Method B: Git Checkout (large rollback, >3 commits)

git checkout 7d3a1f2
git checkout -b rollback-to-v1.2.5
git push origin rollback-to-v1.2.5:main --force

5. Push & Redeploy

git push origin main

Via API (preferido - sincroniza com GUI):

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

# Trigger deploy via API (redeployService NAO existe, usar deployService)
curl -s -X POST "http://localhost:3000/api/trpc/services.app.deployService" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{"projectName":"PROJECT","serviceName":"SERVICE"}}'

Se CI/CD configurado:

• Trigger automático via webhook
• Aguardar build (timeout 5min)

6. Monitor Rollback

# Poll EasyPanel deploy
docker service ps <service>
docker service logs <service> --tail 50 --follow

Timeline:

[00:00] ✅ Git revert completed
[00:05] ✅ Push to Gitea
[01:45] ✅ EasyPanel build started
[03:20] ✅ Container started
[03:28] ✅ Health check: 200 OK

7. Validate Rollback

Health Check (5 retries)

curl -f https://domain/health

Expected: 200 OK

Logs Check

docker logs <container> --tail 100 | grep -i error

Expected: No critical errors

Metrics Check

docker stats <container> --no-stream

Expected:

• CPU < 80%
• RAM < 80%
• No OOM kills

8. Success Report

✅ ROLLBACK COMPLETE

Total time: 3m 30s
Service restored: https://domain.descomplicar.pt
Health: ✅ 200 OK
Version: v1.2.5 (7d3a1f2)

🛠️  NEXT STEPS
1. Investigate root cause: /easypanel-troubleshoot
2. Fix issues locally
3. Test fix: docker build + docker run
4. Redeploy: /easypanel-deploy

Output Format (Success)

🔄 EasyPanel Rollback: dashboard-api

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📜 AVAILABLE VERSIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. v1.3.0 (current) ❌ FAILING
   - Commit: a3f5c21
   - Deployed: 15min ago
   - Health: 502 Bad Gateway
   - Issue: Port mismatch

2. v1.2.5 (previous) ✅ STABLE
   - Commit: 7d3a1f2
   - Deployed: 2h ago
   - Health: 200 OK (before upgrade)
   - Uptime: 99.8% (last 7 days)

3. v1.2.4 ✅ STABLE
   - Commit: 9c4b3a1
   - Deployed: 1 day ago

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

➜ Rollback to: v1.2.5 (recommended)

Confirm? [Y/n]: y

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⏱️  ROLLBACK IN PROGRESS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[00:00] ✅ Git revert (a3f5c21 → 7d3a1f2)
[00:05] ✅ Commit rollback
[00:10] ✅ Push to Gitea
[01:45] ✅ EasyPanel redeploy started
[03:20] ✅ Container started
[03:28] ✅ Health