---
name: easypanel-validate
description: Validação pré-deploy de projectos EasyPanel com health checks, verificação de serviços e auto-fix opcional via API oficial.
layer: 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

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

## Exemplos

```bash
# 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

```bash
# 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):**
```typescript
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

```bash
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)

```bash
# 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)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━