Introducció
Sora Horizon és el panell de control web de la xarxa Sora. Un cop Sora Conductor ha preparat l'orquestrador, Horizon pren el relleu com a punt central de gestió: desplega, configura i monitoritza les màquines virtuals de tot el clúster de Proxmox.
Converteix projectes de Terraform i scripts en un catàleg de plantilles desplegables, i permet desplegar, seguir, modificar i destruir el que generen des de la web, mentre manté en un únic lloc les xarxes, els noms DNS, les ISOs, l'inventari, les credencials i un registre d'auditoria.
Components
Es distribueix en dues peces:
- API: un servei en Bun + Hono sobre PostgreSQL, compilat en un únic binari. Executa Terraform i guarda el seu estat en el seu propi backend HTTP.
- Frontend: una SPA en React + Vite, servida com a fitxers estàtics.
Amb què parla l'API:
| Sistema | Com | Per a què |
|---|---|---|
| Proxmox VE | Token d'API + SSH | Construir ISOs i desplegar VMs mitjançant Terraform |
| Pi-hole | API | Publicar registres DNS i reserves DHCP |
| Nagios | SSH | Escriure els checks de les màquines, validar-los amb nagios -v i reiniciar Nagios |
| Prometheus i Grafana | SSH | Aplicar targets, dashboards, alertes i configuració |
| Keycloak | API d'administració | Gestionar realms, clients, rols, usuaris i aplicacions |
| VMs desplegades | SSH | Executar els scripts i les accions de les plantilles |
| Repositoris Git | HTTPS | Llegir les plantilles, Terraform i scripts |
| Servidors NTP | UDP | Comprovar els servidors amb què sincronitza una VM |
| SMTP | SMTP | Invitacions i recuperació de contrasenya |
El codi de les plantilles es llegeix de Git a cada sincronització, desplegament o execució, i es descarta en acabar. Horizon guarda a la seva base de dades la definició de cada plantilla i el commit que fa servir cada stack.
Instal·lació
La forma prevista és el pas 11 de Conductor, que l'instal·la, el publica a lighttpd, l'afegeix a Nagios, en programa la còpia de seguretat i l'actualitza.
Cada versió es publica al registre de paquets i s'enllaça des de la seva release:
| Fitxer | Contingut |
|---|---|
api.tar.gz | El binari server (linux-x64, inclou Bun) i la carpeta migrations/ |
frontend.tar.gz | La SPA compilada; l'arrel de l'arxiu és l'arrel web |
Cadascun té el seu .sha256. Per a una instal·lació manual: extreure l'API, crear el .env, executar ./server migrate i ./server des de la carpeta extreta; extreure el frontend a l'arrel web i escriure'n l'env.js. Les variables de configuració són al README del projecte.
Abans d'actualitzar, ./server migrate --dry-run executa totes les migracions pendents dins d'una transacció i la desfà: mostra què s'aplicaria i quina fallaria, sense canviar res.
Rols
L'accés és per email i contrasenya. Els usuaris es conviden per correu i estableixen la seva contrasenya amb el mateix enllaç que la recuperació.
| Rol | Pot |
|---|---|
| viewer | Llegir |
| operator | Desplegar i modificar stacks, ISOs, plantilles, xarxa, inventari i monitorització |
| admin | A més, gestionar servidors, credencials, llistes de referència i usuaris |
Seccions
| Secció | Què ofereix | Documentació |
|---|---|---|
| Dashboard | L'estat de tot en una pantalla | a sota |
| Stacks, Startup, ISOs | Desplegar i mantenir les aplicacions | Stacks i ISOs |
| Application i ISO Templates | El catàleg del que es pot desplegar | Plantilles |
| Monitoring | Prometheus, Grafana i Nagios | Monitorització |
| Network, Inventory, Shared folders | IPs, noms DNS, dispositius i carpetes compartides | Xarxa i inventari |
| Keycloak | Realms, clients, usuaris i aplicacions | Keycloak |
| Admin | Servidors, credencials, llistes de referència i usuaris | Configuració |
| Activity | Registre permanent de qui va canviar què | a sota |
Dashboard
La pantalla principal respon a "hi ha alguna cosa en flames?" sense entrar a cap secció:
- Attention: els stacks i ISOs fallits, amb el motiu i un botó per reintentar, i els dominis que encara no tenen xarxa.
- El recompte de stacks per estat i les execucions en curs.
- L'ocupació de cada xarxa (ambre a partir del 90%, vermell a partir del 95%) i els dispositius de l'inventari.
- Stacks per entorn, el catàleg de plantilles i, per als administradors, l'estat dels servidors registrats.
- Els targets de Prometheus i els dashboards de Grafana, si estan registrats, i les darreres entrades d'activitat.
Activity
Un registre permanent on només s'afegeix: creacions, desplegaments, modificacions i esborrats d'stacks, ISOs, adreces, plantilles i recursos d'administració. No s'edita ni s'esborra mai; eliminar un stack no n'elimina la història. Es filtra per dates, usuari i secció. Les entrades d'administració només les veuen els administradors.
Comportament comú
- Les llistes tenen paginació, ordenació i filtres, recorden el seu estat i la seva URL es pot compartir.
- Les operacions llargues (desplegaments, construccions, esborrats) s'executen en segon pla i el seu log es pot llegir mentre passen.
- Els secrets no tornen mai al navegador un cop desats: la web mostra si existeix un valor, no quin és.
- Tema clar i fosc.
Documentació
La documentació del repositori es divideix per audiència:
- docs/contracts: el que una plantilla, script o aplicació de Keycloak ha de complir per funcionar amb Horizon, i les especificacions OpenAPI.
- docs/internal: com està construït Horizon. El seu functionalities.md descriu cada funcionalitat en detall.