# Plan mínimo de CI/CD, healthcheck y backups (pendiente de decisiones)

Este documento describe un plan pragmático y de bajo mantenimiento para asegurar despliegues seguros y copias de seguridad consistentes, sin introducir infra innecesaria. No aplicar todavía: sirve como guía de implementación para la siguiente iteración.

## Contexto actual (resumen)
- Despliegue: push a main en Forgejo → webhook a CapRover → build/deploy con Dockerfile.
- Imagen: basada en oven/bun con utilidades de depuración (curl, netcat, sqlite3). Útil para inspección.
- Healthcheck en Dockerfile “permisivo”: permite éxito aunque /health falle (usa `|| exit 0`).
- Script de arranque con `sleep 10` (resto histórico).
- No hay guardarraíl que bloquee despliegue si fallan tests.

## Objetivos
1) Evitar desplegar una versión rota a producción (guardarraíl mínimo).
2) Mejorar detección temprana de fallos (healthcheck real).
3) Asegurar backups diarios consistentes sin parar el servicio y con verificación de integridad.
4) Mantener la simplicidad operativa.

## Decisiones pendientes (elegir antes de implementar)
- [ ] Disparo de despliegue (elige 1):
  - [ ] A) Desplegar solo con tags (vX.Y.Z). Flujo: tests locales → tag → push → CapRover deploy.
  - [ ] B) Hook server-side en Forgejo (pre-receive/update) que corre `bun test` y rechaza el push si falla.
  - [ ] C) “Webhook gate” mínimo: un endpoint propio que ejecuta tests y reenvía a CapRover solo si pasan.
- [ ] Herramientas en imagen:
  - [x] Mantener sqlite3 por ahora (útil en prod).
  - [ ] Retirar curl y netcat tras piloto (no crítico).
- [ ] Monitor externo muy ligero:
  - [ ] Usar Uptime-Kuma (o similar) para /health cada 1 min.
  - [ ] No usar monitor externo (conformarse con CapRover).
- [ ] Almacenamiento de backups:
  - [ ] Mismo disco (operacional; conservar varias generaciones).
  - [ ] Segundo disco/NAS/otro servidor (preferible si posible).
- [ ] “Smoke” post-deploy:
  - [ ] Enviar DM a BOT_OWNER (si configurado) de “deploy OK”.
  - [ ] Solo registrar métrica (`app_started_at` y `migrations_ok`).

## Cambios planificados (sin aplicar todavía)

### 1) Arranque y healthcheck
- startup.sh: eliminar `sleep 10` y arrancar directamente `bun run index.ts`.
- Dockerfile: endurecer HEALTHCHECK para que falle si /health no responde 200 (eliminar `|| exit 0`). Mantener endpoint básico (sin `full=1`).
- EXPOSE: mantener lectura de PORT por env; sin cambios funcionales.

### 2) Guardarraíl de despliegue (elige 1 opción)
- Opción A — Deploy por tags:
  - Convención de versiones semánticas (vX.Y.Z).
  - Procedimiento: correr `bun test` local → crear tag → push tag → CapRover deploy.
  - Pros: cero infra extra; fácil de revertir en hábitos.
- Opción B — Hook server-side en Forgejo:
  - Añadir hook `pre-receive` (o `update`) que:
    - Chequea que el push es a `refs/heads/main`.
    - Ejecuta `bun test` en un checkout temporal del commit/refs recibido.
    - Si falla, exit ≠ 0 y Forgejo rechaza el push.
  - Pros: no requiere runners ni servicios; bloquea pushes rotos.
- Opción C — Webhook gate mínimo:
  - Service pequeño (script) que recibe el webhook de Forgejo, ejecuta `bun test` y solo si pasa reenvía el webhook a CapRover.
  - Pros: aísla validación del despliegue; Contras: un servicio más que mantener.

### 3) Imagen Docker
- Mantener sqlite3 para inspección en producción.
- Plan (post‑piloto): retirar curl/netcat si no se usan.
- Añadir `.dockerignore` para reducir contexto (node_modules, tests si no son necesarios en build, etc.) — opcional a corto plazo.

### 4) Backups de SQLite (prioridad alta)
- Método recomendado: backup “online” con sqlite3 (sin detener el servicio).
- Procedimiento diario (cron en host o contenedor programador):
  1) Ruta base: `/app/data/tasks.db`.
  2) Crear directorio de backups: `/app/data/backups/`.
  3) Generar nombre con timestamp: `tasks-YYYYMMDD-HHmm.sqlite3`.
  4) Ejecutar backup online:
     - `sqlite3 /app/data/tasks.db ".backup '/app/data/backups/tasks-YYYYMMDD-HHmm.sqlite3'"`.
     - Alternativa: `VACUUM INTO` a un archivo temporal y luego renombrar.
  5) Verificar integridad en la copia:
     - `sqlite3 /app/data/backups/tasks-... "PRAGMA integrity_check;"` debe devolver `ok`.
     - Registrar resultado en un log de backups (`/app/data/backups/backup.log`).
  6) Comprimir (opcional): `gzip -9`.
  7) Retención: mantener p. ej. 7 diarias + 4 semanales; purgar el resto.
- Notas:
  - Con WAL activado, `.backup` maneja consistencia; evita copiar a pelo sin incluir `-wal/-shm`.
  - Si se dispone de otro disco/servidor, replicar las copias (scp/rsync) al menos semanalmente.
- Ensayo mensual de restauración:
  - En un contenedor aislado: montar una copia del backup como `tasks.db` y arrancar la app; comprobar `/health` y que migraciones aplican.

### 5) Detección temprana de fallos
- Healthcheck real (Dockerfile): CapRover marcará “unhealthy” si /health no está OK.
- Smoke post‑deploy:
  - Si se elige DM: encolar un mensaje “deploy OK” a BOT_OWNER tras el arranque (idempotente).
  - Alternativa sin DM: exponer métricas `app_started_at` (epoch ms) y `migrations_ok` (0/1).

### 6) Runbook operativo (resumen)
- Desplegar:
  - Opción A (tags): `bun test` local → `git tag vX.Y.Z` → `git push --tags`.
  - Opción B/C: `git push` a main (tests bloquean si fallan).
- Verificación:
  - CapRover: health verde.
  - `/health` OK; `/metrics` visible.
  - Logs sin errores de migraciones/cola.
- Rollback:
  - CapRover: revertir a la versión previa (history).
- Backup manual (ad hoc):
  - Ejecutar el mismo comando `.backup` y verificar integridad.
- Restore:
  - Parar app (si procede), sustituir `data/tasks.db` por la copia, arrancar, verificar `/health`.

## Checklist de implementación
- [ ] Decidir estrategia de trigger de despliegue (A/B/C).
- [ ] Endurecer HEALTHCHECK en Dockerfile (sin `|| exit 0`).
- [ ] Eliminar `sleep` en startup.sh.
- [ ] (Opcional) Añadir `.dockerignore`.
- [ ] Implementar guardarraíl elegido:
  - [ ] A) Convención de tags y documentación de flujo.
  - [ ] B) Hook en Forgejo con `bun test`.
  - [ ] C) Webhook gate que ejecuta tests y reenvía a CapRover.
- [ ] Programar backup diario con verificación de integridad y retención.
- [ ] Documentar y ensayar restore.
- [ ] (Opcional) Monitor externo para `/health`.
- [ ] (Opcional) Smoke post‑deploy (DM o métricas).

## Impacto esperado
- Riesgo de “romper prod” se reduce significativamente con coste operativo mínimo.
- Backups confiables y verificables sin actividad manual diaria.
- Cambios reversibles y sin bloqueo del desarrollo.