# n8n — Custom Image

Imagen custom de n8n basada en la oficial, con `n8n-nodes-upload-post` preinstalado como bootstrap.

## Versión actual

| Componente | Versión |
|---|---|
| n8n base | `2.15.1` |
| n8n-nodes-upload-post | `0.1.42` |

## Arquitectura

```
Gitea repo (chemavx/n8n)
  └── Dockerfile
        └── FROM n8nio/n8n:2.15.1
              + n8n-nodes-upload-post@0.1.42 (bootstrap)
  └── CI/CD → git.chemavx.xyz/chemavx/n8n:<sha>
        └── k8s-manifests/n8n/deployment-n8n.yaml (parcheado automáticamente)
              └── ArgoCD → despliega en cluster
```

**Nota sobre el nodo custom**: el nodo está instalado en la imagen como fallback. En operación normal, el PVC monta sobre `/home/node/.n8n` y n8n usa la versión del PVC (instalada via UI). Si el PVC se pierde o se usa un volumen nuevo, la imagen ya trae el nodo listo.

## Cómo hacer bump de versión de n8n

1. Revisa el [changelog de n8n](https://github.com/n8n-io/n8n/releases) para breaking changes o migraciones de BD.

2. Edita el `Dockerfile`:
   ```dockerfile
   FROM n8nio/n8n:X.Y.Z   # ← cambiar aquí
   ```

3. Commit y push a `main`:
   ```bash
   git commit -am "chore: bump n8n to X.Y.Z"
   git push
   ```

4. El CI construye la imagen y actualiza el manifiesto automáticamente.

### ⚠️ Advertencia crítica sobre migraciones de BD

n8n ejecuta migraciones de esquema SQLite automáticamente al arrancar con una versión nueva.

**Una vez que el pod arranca con la nueva versión, NO se puede hacer rollback de imagen** si hubo migraciones — la versión antigua no sabe leer el esquema nuevo y n8n no arrancará.

**Regla**: hacer backup ANTES de cualquier bump de versión mayor o minor:

```bash
# 1. Checkpoint WAL
kubectl exec -n n8n deployment/n8n -- node -e "
const sqlite3 = require('/usr/local/lib/node_modules/n8n/node_modules/.pnpm/sqlite3@5.1.7/node_modules/sqlite3');
const db = new sqlite3.Database('/home/node/.n8n/database.sqlite');
db.run('PRAGMA wal_checkpoint(TRUNCATE)', () => { console.log('OK'); db.close(); });
"

# 2. Backup manual
kubectl create job --from=cronjob/backup backup-pre-n8n-upgrade-$(date +%Y%m%d%H%M) -n backup-system
kubectl wait --for=condition=complete job/backup-pre-n8n-upgrade-... -n backup-system --timeout=300s
```

Los bumps de **patch** (2.15.1 → 2.15.2) son generalmente seguros. Los bumps de **minor o major** requieren revisar el changelog.

## Cómo actualizar n8n-nodes-upload-post

Edita el `Dockerfile`:
```dockerfile
RUN ... npm install n8n-nodes-upload-post@X.Y.Z && ...
```

Después actualiza también el nodo desde la UI de n8n para que el PVC quede sincronizado con la imagen.

## Secreto requerido en el cluster

El deployment requiere el secret `n8n-secret` en el namespace `n8n`:

```bash
kubectl create secret generic n8n-secret \
  --from-literal=encryption-key='<VALOR_EN_VAULTWARDEN>' \
  -n n8n
```

**Sin este secret, n8n arranca pero no puede descifrar ninguna credencial.**

## Rollback de emergencia

Si el nuevo deploy falla **antes** de que n8n arranque (imagen no disponible, error de config):

```bash
# Volver a la imagen anterior (sustituir <sha-anterior>)
kubectl set image deployment/n8n n8n=git.chemavx.xyz/chemavx/n8n:<sha-anterior> -n n8n
```

Si n8n ya arrancó con la nueva versión y hubo migraciones, no hacer rollback de imagen — restaurar desde backup.