78 lines
4.6 KiB
Markdown
78 lines
4.6 KiB
Markdown
# Capability: local-hub
|
|
|
|
Exponer los procesos locales de la maquina como subdominios `*.localhost` (via Caddy) y reunirlos
|
|
en una pantalla principal (Glance) con estado online/offline en vivo, refrescada a diario por
|
|
`dag_engine`. Cubre el ciclo: descubrir servicios -> renderizar config de proxy -> renderizar
|
|
config de dashboard -> recargar y reiniciar (pipeline `refresh_local_hub`).
|
|
|
|
Fuente de verdad de los servicios: `apps/local_hub/local_services.yaml`.
|
|
|
|
## Por que existe
|
|
|
|
Una maquina con muchos procesos locales (Metabase :3030, Portainer :9000, Grafana, Jupyter,
|
|
dag_engine, registry_api...) obliga a recordar puerto por puerto. Este grupo los pone detras de
|
|
nombres legibles (`metabase.localhost`, `portainer.localhost`) sin tocar DNS ni `/etc/hosts`
|
|
(systemd-resolved resuelve `*.localhost` a 127.0.0.1 por defecto, RFC 6761) y los lista en una
|
|
sola pagina con su salud en vivo.
|
|
|
|
## Funciones
|
|
|
|
| ID | Firma | Que hace |
|
|
|---|---|---|
|
|
| `discover_local_services_py_infra` | `discover_local_services(manifest_path, include_registry=True) -> list[dict]` | Lee el manifiesto `local_services.yaml`, normaliza cada servicio (name, subdomain, port, health_path, title, icon, category) y resuelve `up` por chequeo TCP. Con `include_registry` anade los servicios del registry (via `fn doctor services-spec`) deduplicados. |
|
|
| `render_caddyfile_py_infra` | `render_caddyfile(services, dashboard=None) -> str` | PURA. Convierte la lista de servicios en el texto de un fragmento de Caddyfile (`http://<sub>.localhost { reverse_proxy 127.0.0.1:<port> }`), ordenado y determinista. El dashboard va primero. |
|
|
| `render_glance_config_py_infra` | `render_glance_config(services, title="Procesos locales", host_suffix="localhost") -> str` | PURA. Convierte la lista en YAML de Glance: una pagina con un widget `monitor` por categoria, cada site apuntando a `http://<sub>.localhost`. |
|
|
| `refresh_local_hub_py_pipelines` | `refresh_local_hub(manifest_path=..., reload=True) -> dict` | PIPELINE. Compone las 3 anteriores: descubre, renderiza Caddyfile + Glance, los escribe (`/etc/caddy/conf.d/local_hub.caddy` via ACL + `apps/local_hub/glance/glance.yml`), recarga Caddy (admin API :2019, sin sudo) y reinicia la user-unit `glance`. |
|
|
|
|
## Ejemplo canonico
|
|
|
|
```bash
|
|
# Refrescar todo el hub (descubrir + regenerar configs + recargar):
|
|
./fn run refresh_local_hub
|
|
|
|
# Acceder a un servicio por su subdominio (cualquier navegador del host):
|
|
# http://metabase.localhost
|
|
# http://portainer.localhost
|
|
# http://home.localhost <- la pantalla principal (Glance)
|
|
|
|
# Anadir un servicio nuevo: editar el manifiesto y refrescar
|
|
$EDITOR apps/local_hub/local_services.yaml # name, subdomain, port, health_path, title, icon, category
|
|
./fn run refresh_local_hub
|
|
```
|
|
|
|
Composicion ad-hoc (heredoc) si se necesita solo una parte:
|
|
|
|
```python
|
|
import sys, os
|
|
sys.path.insert(0, os.path.join("python", "functions"))
|
|
from infra.discover_local_services import discover_local_services
|
|
from infra.render_caddyfile import render_caddyfile
|
|
|
|
services = discover_local_services("apps/local_hub/local_services.yaml")
|
|
print(render_caddyfile(services, dashboard={"subdomain": "home", "port": 8585}))
|
|
```
|
|
|
|
## Infraestructura (one-time, ya provisionada)
|
|
|
|
- **Caddy** (`apt`, systemd system service, puerto 80): `/etc/caddy/Caddyfile` hace
|
|
`import /etc/caddy/conf.d/*.caddy`. El usuario tiene ACL de escritura sobre `conf.d/` para que
|
|
el pipeline regenere sin sudo. Reload via admin API en `localhost:2019`.
|
|
- **Glance** (binario nativo en `~/.local/bin/glance`, systemd user service `glance.service`,
|
|
`127.0.0.1:8585`). Corre como binario del host —no contenedor— para que `*.localhost` resuelva
|
|
igual que en el resto del sistema.
|
|
- **dag_engine**: DAG `refresh_local_hub` diario que ejecuta el pipeline.
|
|
|
|
## Fronteras
|
|
|
|
- **NO gestiona TLS**: sirve HTTP plano (`http://`) porque es trafico loopback. Para HTTPS con CA
|
|
interna habria que quitar el prefijo `http://` en `render_caddyfile` y dejar que Caddy emita
|
|
certs internos.
|
|
- **NO arranca ni para los servicios** que expone: asume que ya corren. Solo crea el mapeo de
|
|
subdominio y los lista. Encender/apagar un servicio es trabajo de su propia unit / `systemd`.
|
|
- **NO hace el health-check en vivo**: eso lo hace Glance client-side. El pipeline solo resuelve
|
|
un `up/down` puntual al regenerar (snapshot del momento).
|
|
- **Servicios no-HTTP** (Postgres :5433, etc.) quedan fuera del proxy y del dashboard: Caddy y el
|
|
widget `monitor` de Glance son HTTP.
|
|
- **Solo loopback / un PC**: el manifiesto y los subdominios son locales a la maquina. No expone
|
|
nada a la red. Para acceso remoto se usa SSH port-forward o el grupo `ssh`/`wireguard`.
|