Operación y mantenimiento

Para qué es este capítulo

Una vez Gestión Civis está en marcha, hay que vigilarlo, actualizarlo y respaldarlo para que siga funcionando con fiabilidad. Esta guía recoge las tareas habituales de operación, pensadas también para quien tiene poca experiencia administrando servidores.

Da por hecho un despliegue como el de las guías de servidor o Google Cloud (backend con systemd, Nginx, PostgreSQL y el scheduler por cron).

1. Comprobaciones rápidas (¿está todo bien?)

Un repaso de 1 minuto para confirmar que la plataforma está sana:

# ¿El backend está corriendo?
sudo systemctl status gestion-civis

# ¿Responde la API? (debe devolver JSON con la lista de rutas)
curl -s https://civis.tu-ayuntamiento.es/api/_routes | head -c 200

# ¿Está Nginx activo?
sudo systemctl status nginx

# ¿La base de datos acepta conexiones?
sudo -u postgres psql -c "SELECT 1;"

Si…	Entonces…
`systemctl status` muestra active (running)	el servicio está bien.
Aparece failed o inactive	revisa los logs y reinícialo.
La API no responde pero el servicio corre	suele ser Nginx o el firewall; revisa el log de Nginx.

2. Estado del sistema y tareas automáticas (MOS)

El motor MOS expone, para usuarios con permiso, pantallas y endpoints de salud:

Estado del planificador: GET /api/core/scheduler/status — muestra el estado de la cola de eventos y de las tareas programadas.
Salud del sistema: GET /api/core/admin/system-health — incluye el tamaño de las tablas de auditoría (que crecen con el uso).

Además, conviene vigilar que el scheduler se está ejecutando (es el que dispara SIR, avisos, prescripciones, proyección, SLA…):

# Últimas ejecuciones del scheduler (cron de la guía de servidor)
sudo tail -n 30 /opt/gestion-civis/logs/scheduler.log

Si el scheduler no corre, se paran los automatismos

Si ese log no se actualiza cada pocos minutos, las tareas automáticas no se están ejecutando: revisa el cron (servidor) o el job programado (Google Cloud). Síntomas típicos: los envíos SIR no salen, no llegan avisos de vencimiento.

3. Registros (logs)

Saber dónde mirar cuando algo falla:

Qué	Dónde	Comando
Backend (errores de la app, arranque)	journal de systemd	`sudo journalctl -u gestion-civis -f`
Scheduler (tareas automáticas)	fichero de log	`sudo tail -f /opt/gestion-civis/logs/scheduler.log`
Nginx (acceso y errores web)	`/var/log/nginx/`	`sudo tail -f /var/log/nginx/error.log`
Presupuesto (log propio del módulo)	`logs/presupuesto.log`	`sudo tail -f /opt/gestion-civis/logs/presupuesto.log`
PostgreSQL	log de Postgres	`sudo tail -f /var/log/postgresql/*.log`

Buscar un error concreto

-f muestra el log en vivo (Ctrl+C para salir). Para buscar algo pasado: sudo journalctl -u gestion-civis --since "today" | grep -i error.

Trazabilidad funcional

Aparte de estos logs técnicos, la actividad de negocio (quién hizo qué) queda en el Historial del sistema dentro de la aplicación (ver Historial y auditoría).

4. Actualizar a una versión nueva (con seguridad)

Haz copia de seguridad ANTES de actualizar

Una actualización aplica migraciones que modifican la base de datos. Si algo sale mal, la copia previa es tu seguro. No te saltes el paso 1.

# 1) COPIA DE SEGURIDAD previa (ver sección 5)
sudo -u postgres pg_dump gestion_civis > /ruta/segura/pre_update_$(date +%F_%H%M).sql

# 2) Actualizar el código y las dependencias
sudo su - civis
cd /opt/gestion-civis
git pull
source .venv/bin/activate
pip install -r requirements.txt

# 3) Aplicar migraciones de base de datos
flask db upgrade

# 4) Si cambió el frontend, recompilarlo
cd gestion-civis-frontend && npm install && npm run build
exit
sudo cp -r /opt/gestion-civis/gestion-civis-frontend/dist/* /var/www/civis/

# 5) Reiniciar el backend
sudo systemctl restart gestion-civis

Después, repasa las comprobaciones rápidas y prueba un login.

Si una actualización falla

Revisa el error en journalctl -u gestion-civis.
Si el problema está en la base de datos y no se resuelve, restaura la copia previa (sección 5) y vuelve a la versión anterior del código (git checkout <versión-anterior>).

Probar primero en un entorno de pruebas

Lo ideal es tener una copia del servidor (o una VM aparte) donde ensayar la actualización antes de aplicarla en producción.

5. Copias de seguridad y restauración

Son dos cosas las que hay que respaldar: la base de datos y los ficheros.

Copia de seguridad

# Base de datos (texto comprimido)
sudo -u postgres pg_dump -Fc gestion_civis > /ruta/segura/civis_db_$(date +%F).dump

# Ficheros (si STORAGE_PROVIDER=local)
sudo tar czf /ruta/segura/civis_files_$(date +%F).tar.gz /opt/gestion-civis/storage

Reglas de oro de los backups

Automatízalos (un cron diario) y guárdalos fuera del servidor.
Comprueba que se pueden restaurar (un backup que no se ha probado no es un backup).
Conserva varias copias (p. ej. diarias de la última semana + una mensual).

Restauración (en caso de desastre)

# Restaurar la base de datos (¡sobreescribe los datos actuales!)
sudo -u postgres pg_restore -d gestion_civis --clean /ruta/segura/civis_db_FECHA.dump

# Restaurar los ficheros
sudo tar xzf /ruta/segura/civis_files_FECHA.tar.gz -C /
sudo systemctl restart gestion-civis

En Google Cloud

Cloud SQL hace copias automáticas si las activas (recomendado), y permite restaurar a un punto en el tiempo. Los ficheros viven en el bucket de Cloud Storage, donde puedes activar el versionado de objetos para recuperar borrados.

6. Mantenimiento de la base de datos

PostgreSQL se mantiene casi solo, pero conviene:

Vigilar el espacio: las tablas de auditoría de MOS crecen con el uso (están particionadas por fecha). Consulta su tamaño con GET /api/core/admin/system-health o desde PostgreSQL.

Espacio en disco del servidor:

df -h                      # espacio libre en disco
du -sh /opt/gestion-civis/storage   # cuánto ocupan los ficheros

PostgreSQL ejecuta autovacuum automáticamente; no suele requerir intervención.

Plan de retención de auditoría

Si el histórico de auditoría llega a ser muy grande tras años de uso, valora con el equipo técnico una política de archivado/retención de las particiones antiguas.

7. Rendimiento

Workers de gunicorn: si la aplicación va lenta con muchos usuarios, puedes subir el número de workers (-w) en el servicio systemd, siempre que haya RAM suficiente (cada worker que use IA consume memoria). Si se queda sin memoria, bájalos.
Búsqueda semántica: si los resultados de búsqueda se quedan desactualizados, existe la opción de reindexar desde la administración del módulo Documental.

Vigila CPU/RAM:

top            # uso de CPU y memoria en vivo (q para salir)
free -h        # memoria disponible

8. Seguridad continua

Actualiza el sistema operativo periódicamente:
```
sudo apt update && sudo apt upgrade -y
```
Certificado HTTPS: con Certbot se renueva solo; comprueba que el temporizador está activo (systemctl status certbot.timer).
Usuarios y permisos: revisa periódicamente las cuentas activas y sus roles; desactiva las que ya no se usen. Fomenta el doble factor (MFA).
SECRET_KEY y credenciales (SIR, FACe, GCS): mantenlas en el .env, nunca en el código ni en copias compartidas.
Firewall: solo deben estar abiertos los puertos 80/443 (web) y un 22 (SSH) restringido.

9. Checklist de operación

En resumen

Mantén copias de seguridad probadas, vigila que el backend y el scheduler estén vivos, revisa los logs cuando algo falle y aplica las actualizaciones con una copia previa. Con eso, la operación del día a día será tranquila.