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

name, description, layer

name	description	layer
easypanel-validate	Validação pré-deploy de projectos EasyPanel com health checks, verificação de serviços e auto-fix opcional via API oficial.	wiki

EasyPanel Validate

Validação pré-deploy de projectos EasyPanel com auto-fix opcional.

Quando Usar

• Antes de deploy (pre-flight check)
• Após criar novo projecto
• Para auditar projecto existente
• Quality gate antes de commit
• CI/CD validation step

Sintaxe

/easypanel-validate [--fix] [--strict]

Exemplos

# Validação sem correcções
/easypanel-validate

# Validação com auto-fix (cria ficheiros em falta)
/easypanel-validate --fix

# Modo strict (fail on warnings)
/easypanel-validate --strict

Validation Checks (10 categorias)

1. Check Dockerfile

# Lint com hadolint (Docker best practices)
hadolint Dockerfile

Checks:

• ✅ Multi-stage build (>= 2 stages)
• ✅ FROM com versão específica (not :latest)
• ✅ HEALTHCHECK presente
• ✅ USER non-root
• ✅ EXPOSE port
• ⚠️ Warnings: npm install (usar npm ci), COPY . antes package.json

Auto-fix (--fix):

• Adicionar USER nodejs se ausente
• Adicionar HEALTHCHECK se ausente
• Sugerir multi-stage (não altera automaticamente)

2. Check .dockerignore

Checks:

• ✅ Existe
• ✅ Espelha .gitignore (node_modules, dist, .env)
• ❌ Se não existe → --fix: criar automaticamente

Auto-fix (--fix):

node_modules
dist
build
.env
.env.local
*.log
.git
.DS_Store

3. Check docker-compose.yml

Checks:

• ✅ Traefik labels presentes
• ✅ router.rule com domain
• ✅ service.loadbalancer.server.port match Dockerfile EXPOSE
• ✅ healthcheck.path configurado (/health)
• ⚠️ Warnings: certresolver não é letsencrypt, restart policy não definida

Auto-fix (--fix):

• Adicionar restart: unless-stopped
• Corrigir sintaxe de labels Traefik

4. Check package.json (Node.js)

Checks:

• ✅ Scripts: build, start, lint, test
• ✅ Dependencies: express/fastify (API framework)
• ⚠️ devDependencies em dependencies (bloat)

5. Check Health Endpoint

Checks:

• ✅ Ficheiro existe (src/routes/health.ts ou similar)
• ✅ GET /health implementado
• ❌ Se não existe → --fix: criar template

Template Health Endpoint (Node.js/Express):

import { Router } from 'express'

const router = Router()

router.get('/health', (req, res) => {
  res.status(200).json({
    status: 'ok',
    timestamp: new Date().toISOString(),
    uptime: process.uptime()
  })
})

export default router

6. Check .gitignore

Checks:

• ✅ node_modules
• ✅ dist/build
• ✅ .env (não .env.example)
• ✅ logs/

7. Check .env.example

Checks:

• ✅ Existe (template para .env)
• ✅ Todas vars documentadas
• ⚠️ Valores default sensíveis (passwords)

8. Check CI/CD

Checks:

• ✅ .gitea/workflows/deploy.yml existe
• ✅ Webhook URL configurado (secret)
• ⚠️ Tests não rodando (npm test ausente)

Auto-fix (--fix):

• Criar .gitea/workflows/deploy.yml usando template

9. Test Local Build

docker build --no-cache -t test:validate .

Checks:

• Build completa sem erros
• Image size < 200MB (Node.js)
• Image size > 200MB (optimizar multi-stage)

10. Validar Serviço via API (se já deployed)

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

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

# Verificar estatisticas de recursos
curl -s "http://localhost:3000/api/trpc/monitor.getSystemStats" \
  -H "Authorization: Bearer $TOKEN"

11. Output Report

Score: X/10

• Cada categoria = 1 ponto
• Critical issues = 0 pontos
• Warnings = 0.5 pontos

Output Format

🔍 EasyPanel Deploy Validation

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 SCORE: X/10 (EXCELLENT | GOOD | FAIR | POOR)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ PASSED (X)
   1. Dockerfile: Multi-stage build
   2. docker-compose.yml: Traefik configured
   ...

⚠️  WARNINGS (X)
   1. Dockerfile: Use 'npm ci' instead of 'npm install'
   2. docker-compose.yml: Missing restart policy
   ...

❌ CRITICAL (X)
   1. .dockerignore: FILE MISSING
      → Impact: Build includes unnecessary files
      → Fix: Create .dockerignore

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔧 AUTO-FIXES (--fix flag detected)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Created .dockerignore
✅ Updated docker-compose.yml: Added restart policy
✅ Dockerfile: Changed npm install → npm ci

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 RECOMMENDATIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. Add .gitea/workflows/deploy.yml for CI/CD
2. Implement integration tests
3. Consider Prometheus metrics endpoint (/metrics)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ READY TO DEPLOY (score >= 7/10)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━