Introducción
Sora Horizon es el panel de control web de la red Sora. Una vez Sora Conductor ha preparado el orquestador, Horizon toma el relevo como punto central de gestión: despliega, configura y monitoriza las máquinas virtuales de todo el clúster de Proxmox.
Convierte proyectos de Terraform y scripts en un catálogo de plantillas desplegables, y permite desplegar, seguir, modificar y destruir lo que generan desde la web, mientras mantiene en un único sitio las redes, los nombres DNS, las ISOs, el inventario, las credenciales y un registro de auditoría.
Componentes
Se distribuye en dos piezas:
- API: un servicio en Bun + Hono sobre PostgreSQL, compilado en un único binario. Ejecuta Terraform y guarda su estado en su propio backend HTTP.
- Frontend: una SPA en React + Vite, servida como ficheros estáticos.
Con qué habla la API:
| Sistema | Cómo | Para qué |
|---|---|---|
| Proxmox VE | Token de API + SSH | Construir ISOs y desplegar VMs mediante Terraform |
| Pi-hole | API | Publicar registros DNS y reservas DHCP |
| Nagios | SSH | Escribir los checks de las máquinas, validarlos con nagios -v y reiniciar Nagios |
| Prometheus y Grafana | SSH | Aplicar targets, dashboards, alertas y configuración |
| Keycloak | API de administración | Gestionar realms, clientes, roles, usuarios y aplicaciones |
| VMs desplegadas | SSH | Ejecutar los scripts y acciones de las plantillas |
| Repositorios Git | HTTPS | Leer las plantillas, Terraform y scripts |
| Servidores NTP | UDP | Comprobar los servidores con los que sincroniza una VM |
| SMTP | SMTP | Invitaciones y recuperación de contraseña |
El código de las plantillas se lee de Git en cada sincronización, despliegue o ejecución, y se descarta al terminar. Horizon guarda en su base de datos la definición de cada plantilla y el commit que usa cada stack.
Instalación
La forma prevista es el paso 11 de Conductor, que lo instala, lo publica en lighttpd, lo añade a Nagios, programa su copia de seguridad y lo actualiza.
Cada versión se publica en el registro de paquetes y se enlaza desde su release:
| Fichero | Contenido |
|---|---|
api.tar.gz | El binario server (linux-x64, incluye Bun) y la carpeta migrations/ |
frontend.tar.gz | La SPA compilada; la raíz del archivo es la raíz web |
Cada uno tiene su .sha256. Para una instalación manual: extraer la API, crear el .env, ejecutar ./server migrate y ./server desde la carpeta extraída; extraer el frontend en la raíz web y escribir su env.js. Las variables de configuración están en el README del proyecto.
Antes de actualizar, ./server migrate --dry-run ejecuta todas las migraciones pendientes dentro de una transacción y la deshace: muestra qué se aplicaría y cuál fallaría, sin cambiar nada.
Roles
El acceso es por email y contraseña. Los usuarios se invitan por correo y establecen su contraseña con el mismo enlace que la recuperación.
| Rol | Puede |
|---|---|
| viewer | Leer |
| operator | Desplegar y modificar stacks, ISOs, plantillas, red, inventario y monitorización |
| admin | Además, gestionar servidores, credenciales, listas de referencia y usuarios |
Secciones
| Sección | Qué ofrece | Documentación |
|---|---|---|
| Dashboard | El estado de todo en una pantalla | abajo |
| Stacks, Startup, ISOs | Desplegar y mantener las aplicaciones | Stacks e ISOs |
| Application e ISO Templates | El catálogo de lo que se puede desplegar | Plantillas |
| Monitoring | Prometheus, Grafana y Nagios | Monitorización |
| Network, Inventory, Shared folders | IPs, nombres DNS, dispositivos y carpetas compartidas | Red e inventario |
| Keycloak | Realms, clientes, usuarios y aplicaciones | Keycloak |
| Admin | Servidores, credenciales, listas de referencia y usuarios | Configuración |
| Activity | Registro permanente de quién cambió qué | abajo |
Dashboard
La pantalla principal responde a "¿hay algo en llamas?" sin entrar en ninguna sección:
- Attention: los stacks e ISOs fallidos, con el motivo y un botón para reintentar, y los dominios que aún no tienen red.
- El recuento de stacks por estado y las ejecuciones en curso.
- La ocupación de cada red (ámbar a partir del 90%, rojo a partir del 95%) y los dispositivos del inventario.
- Stacks por entorno, el catálogo de plantillas y, para los administradores, el estado de los servidores registrados.
- Los targets de Prometheus y los dashboards de Grafana, si están registrados, y las últimas entradas de actividad.
Activity
Un registro permanente y de solo añadir: creaciones, despliegues, modificaciones y borrados de stacks, ISOs, direcciones, plantillas y recursos de administración. Nunca se edita ni se borra; eliminar un stack no elimina su historia. Se filtra por fechas, usuario y sección. Las entradas de administración solo las ven los administradores.
Comportamiento común
- Las listas tienen paginación, ordenación y filtros, recuerdan su estado y su URL se puede compartir.
- Las operaciones largas (despliegues, construcciones, borrados) se ejecutan en segundo plano y su log se puede leer mientras ocurren.
- Los secretos nunca vuelven al navegador una vez guardados: la web muestra si existe un valor, no cuál es.
- Tema claro y oscuro.
Documentación
La documentación del repositorio se divide por audiencia:
- docs/contracts: lo que una plantilla, script o aplicación de Keycloak debe cumplir para funcionar con Horizon, y las especificaciones OpenAPI.
- docs/internal: cómo está construido Horizon. Su functionalities.md describe cada funcionalidad en detalle.