Skip to content

SIVA con Podman ​

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

Requisitos ​

HerramientaInstalación
Podmansudo apt install podman (Debian/Ubuntu) o https://podman.io
podman-composepip install podman-compose o sudo apt install podman-compose

Verifica la instalación:

bash
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:

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

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

DirectorioPropósitoPersistencia
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/:

bash
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:

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

ServicioURL
Frontend (HMR)http://localhost:5173
Backend APIhttp://localhost:3000/api
Swagger Docshttp://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/:

bash
cd podman
podman-compose up -d --build

Accesos ​

ServicioURL
Frontend (nginx)http://localhost:5173
Backend APIhttp://localhost:3000/api
Swagger Docshttp://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/.

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

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

Variables principales ​

VariableDefaultDescripción
JWT_SECRETsiva-jwt-secret-change-in-productionSecreto para firmar tokens JWT. Cámbialo en producción.
SUPERADMIN_EMAILsuperadmin@inap.esEmail del superadministrador inicial (obligatorio)
SUPERADMIN_PASSWORDsuperadmin1234Contraseña del superadministrador inicial (obligatorio)
LAURA_EMAIL / LAURA_PASSWORDlaura.lopezr@inap.es / laura1234Cuenta de desarrollo
SUPERVISOR_EMAIL / SUPERVISOR_PASSWORDsupervisor@inap.es / supervisor1234Cuenta de desarrollo
CORS_ORIGINhttp://localhost:5173Origen permitido para CORS
BACKEND_PORT3000Puerto del backend en el host
FRONTEND_PORT5173Puerto del frontend en el host
SMTP_PORT1025Puerto SMTP de Mailpit en el host
SMTP_WEB_PORT8025Puerto 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:

bash
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:

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

El backend no arranca ​

Revisá los logs:

bash
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:

bash
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:

bash
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:

dockerfile
# 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

SIVA — Sistema Integral de Vigilantes de Aulas