SIVA con Podman

Documentación técnica interna. Los scripts viven en deploy/podman/ del repositorio. Índice general: docs/README.md.

Requisitos

Herramienta	Instalación
Podman	sudo apt install podman (Debian/Ubuntu) o https://podman.io
podman-compose	pip install podman-compose o sudo apt install podman-compose

Verifica la instalación:

podman --version
podman-compose --version

---

Primer arranque

Ejecuta el script de configuración una sola vez desde la carpeta deploy/podman/. Crea los directorios de datos y copia los assets estáticos:

cd podman
chmod +x setup.sh
./setup.sh

El script genera tres directorios dentro de deploy/podman/:

Directorio	Propósito	Persistencia
deploy/podman/data/	Base de datos SQLite (siva.db)	Sobrevive a reinicios y rebuilds
deploy/podman/storage/	Archivos subidos (avatars)	Sobrevive a reinicios y rebuilds
deploy/podman/public/	Assets estáticos (logos, favicon)	Copiados desde backend/public/ la primera vez

---

Desarrollo

Backend, frontend y Mailpit corren en contenedores con live reload activo en ambos.

Todos los comandos se ejecutan desde la carpeta deploy/podman/:

cd podman
./dev.sh

Esto levanta los 3 servicios en primer plano. Ctrl+C detiene todo.

Si preferís lanzar el frontend en el host (HMR más rápido), usá compose directamente:

# Terminal 1 — backend + mailpit
podman-compose -f podman-compose.dev.yml up backend mailpit --build

# Terminal 2 — frontend en host
cd ../frontend && npm run dev

Accesos

Servicio	URL
Frontend (HMR)	http://localhost:5173
Backend API	http://localhost:3000/api
Swagger Docs	http://localhost:3000/api/docs
Mailpit (correos)	http://localhost:8025

Live reload

• Backend: tsx watch detecta cambios en backend/src/ y reinicia automáticamente. Los fuentes están montados como volumen.
• Frontend: Vite HMR en contenedor. Cambios en frontend/src/ se reflejan al instante. Los fuentes y la configuración de Vite están montados como volumen.

Notas de desarrollo

• Si añadís una dependencia nueva en package.json, reconstruí la imagen: podman-compose -f podman-compose.dev.yml up --build
• El proxy de Vite apunta a http://backend:3000 dentro de la red de contenedores (variable API_TARGET en el compose). Si lanzás el frontend en el host, la variable no está definida y Vite usa http://localhost:3000 por defecto.
• Mailpit captura todos los correos que envía el backend. Para verlos, abrí http://localhost:8025.

---

Producción

Todos los servicios corren en contenedores. El frontend se compila con vite build y nginx sirve los archivos estáticos haciendo reverse proxy al backend.

Ejecuta desde la carpeta deploy/podman/:

cd podman
podman-compose up -d --build

Accesos

Servicio	URL
Frontend (nginx)	http://localhost:5173
Backend API	http://localhost:3000/api
Swagger Docs	http://localhost:3000/api/docs
Mailpit (correos)	http://localhost:8025

Servicios en producción

┌─────────────────────────────────────┐
│  podman-compose (prod)              │
│                                     │
│  ┌──────────┐  ┌──────────┐        │
│  │ frontend  │  │  backend  │        │
│  │ (nginx)   │──│ (node)    │        │
│  │  :80      │  │  :3000    │        │
│  └──────────┘  └──────────┘        │
│       :5173         :3000            │
│       ▲              ▲               │
│  ┌────┴──────────────┴───┐          │
│  │       mailpit         │          │
│  │       :1025 :8025     │          │
│  └───────────────────────┘          │
│                                     │
│  Volúmenes:                         │
│    deploy/podman/data     → /app/data      │
│    deploy/podman/storage  → /app/storage   │
│    deploy/podman/public   → /app/public    │
└─────────────────────────────────────┘

---

Comandos útiles

Todos los comandos se ejecutan desde la carpeta deploy/podman/.

# Ver logs
podman-compose logs -f backend

# Ver todos los logs
podman-compose logs -f

# Detener servicios
podman-compose down             # producción
podman-compose -f podman-compose.dev.yml down   # desarrollo

# Reconstruir sin cache
podman-compose build --no-cache

# Entrar al contenedor del backend
podman exec -it siva-backend sh

# Ver estado de los contenedores
podman ps

---

Variables de entorno

Las variables se definen directamente en el archivo compose (environment:). Podés sobrescribirlas creando un archivo .env en la carpeta deploy/podman/ o exportándolas antes de ejecutar compose.

# deploy/podman/.env (opcional)
JWT_SECRET=tu-secreto-seguro-aqui
CORS_ORIGIN=https://tu-dominio.com
BACKEND_PORT=3000
FRONTEND_PORT=8080

Variables principales

Variable	Default	Descripción
JWT_SECRET	siva-jwt-secret-change-in-production	Secreto para firmar tokens JWT. Cámbialo en producción.
SUPERADMIN_EMAIL	superadmin@inap.es	Email del superadministrador inicial (obligatorio)
SUPERADMIN_PASSWORD	superadmin1234	Contraseña del superadministrador inicial (obligatorio)
LAURA_EMAIL / LAURA_PASSWORD	laura.lopezr@inap.es / laura1234	Cuenta de desarrollo
SUPERVISOR_EMAIL / SUPERVISOR_PASSWORD	supervisor@inap.es / supervisor1234	Cuenta de desarrollo
CORS_ORIGIN	http://localhost:5173	Origen permitido para CORS
BACKEND_PORT	3000	Puerto del backend en el host
FRONTEND_PORT	5173	Puerto del frontend en el host
SMTP_PORT	1025	Puerto SMTP de Mailpit en el host
SMTP_WEB_PORT	8025	Puerto web de Mailpit en el host

---

Migraciones y base de datos

El backend ejecuta las migraciones automáticamente al iniciar (migrationsRun: true). Esto implica:

• En el primer arranque, se crea la base de datos y se insertan los datos iniciales (superadmin, plantillas, datos de prueba).
• En arranques posteriores, las migraciones nuevas se aplican automáticamente.

El archivo siva.db se guarda en deploy/podman/data/ (volumen persistente). Para resetear la base de datos:

rm data/siva.db
podman-compose up -d

---

Solución de problemas

Error de permisos en volúmenes

Con Podman rootless, los archivos en los bind mounts pueden tener problemas de permisos si el UID dentro del contenedor no coincide con el del host.

Solución: Asegurate de que los directorios deploy/podman/data/, deploy/podman/storage/ y deploy/podman/public/ tengan permisos de escritura para tu usuario:

chmod -R 755 deploy/podman/data deploy/podman/storage deploy/podman/public

El backend no arranca

Revisá los logs:

podman-compose logs backend

Causas comunes:

• deploy/podman/data/ no existe o no tiene permisos de escritura.
• deploy/podman/public/ no contiene los assets estáticos (ejecutá ./setup.sh).

No puedo conectar al backend desde el frontend en desarrollo

Verificá que vite.config.ts tenga el proxy apuntando a http://localhost:3000 y que el contenedor del backend esté corriendo:

curl http://localhost:3000/api/health

Cambios en backend/src/ no se detectan (dev)

tsx watch usa inotify. En algunos sistemas de archivos (NFS, mounts fuse-overlayfs) puede fallar. Como alternativa, podés forzar poll mode con la variable de entorno:

CHOKIDAR_USEPOLLING=true podman-compose -f podman-compose.dev.yml up

Error node:24-alpine: image not found

Si la imagen node:24-alpine no existe aún en Docker Hub, cambiá la versión en los Dockerfiles. Por ejemplo, node:22-alpine o node:lts-alpine:

# En backend/Dockerfile y frontend/Dockerfile, reemplazá:
FROM docker.io/library/node:24-alpine AS base
# por:
FROM docker.io/library/node:lts-alpine AS base