Fundaia

Entrar Empezar

Varios servidores

Una instancia de Fundaia empieza en una máquina, la principal, donde corre la plataforma. Puedes añadirle más servidores: la plataforma los maneja con podman remoto por SSH, sin instalar nada más en ellos, y reparte los entornos entre todos.

  • Cada entorno vive entero en un servidor: sus contenedores, su red privada y sus volúmenes. Así postgres:5432 sigue funcionando entre servicios del mismo entorno sin tocar nada.
  • Un entorno nuevo va al servidor con más memoria libre, decidido en su primer despliegue. Los entornos que ya existían siguen en la principal hasta que los mudes.
  • La pasarela sigue en la principal: todas las peticiones entran por ella y se reenvían a la dirección privada del servidor donde corre el servicio. Dominios, caché, contraseñas, modo mantenimiento y el despertar funcionan igual.

Preparar un servidor

Una máquina Linux con systemd y podman (4.4 o más nuevo). La plataforma tiene su propia clave SSH (ed25519, creada la primera vez que hace falta y guardada en su carpeta, legible solo por ella), y te da un comando que deja la máquina lista. Cópialo de Servidores → Añadir servidor, o:

fundaia servers bootstrap            # el comando y la clave pública
fundaia servers bootstrap --script   # el script, para leerlo antes

Por MCP: read_server_bootstrap.

Ejecútalo en la máquina nueva como root (lleva sudo dentro). Sin instalar nada más:

  1. Crea el usuario sin privilegios (deploy, o el de --user) y sus rangos de subuid.
  2. Activa loginctl enable-linger, para que sus contenedores sobrevivan a cerrar la sesión.
  3. Deja podman.socket en marcha para ese usuario: la API que habla la plataforma.
  4. Añade la clave pública de la plataforma a su ~/.ssh/authorized_keys, una sola vez.
  5. Imprime la conexión y la dirección que pegar al añadirlo, y el fundaia servers add entero.

La dirección que imprime es la de Tailscale si la hay, o la de la salida por defecto: si no es la de la red privada, cámbiala por esa.

A mano

Lo mismo, paso a paso, en el servidor nuevo:

sudo loginctl enable-linger deploy          # sus contenedores sobreviven a cerrar la sesión
systemctl --user enable --now podman.socket  # como deploy: la API que habla la plataforma
id -u                                        # el número que va en la ruta del socket

Y autoriza una clave: pega la pública de la plataforma en ~/.ssh/authorized_keys de deploy, o desde la máquina principal, con el usuario que ejecuta la plataforma, ssh-copy-id deploy@10.0.0.5. Sin clave indicada, la plataforma prueba primero la suya y después la de siempre de esa máquina.

Las dos máquinas deben verse por una red privada (la LAN, WireGuard o Tailscale): los contenedores del servidor publican sus puertos en esa dirección y la principal los alcanza por ella. No abras esos puertos a internet; cierra el resto con el cortafuegos.

Añadir un servidor

En Servidores (solo el administrador de la instancia), Añadir servidor: pega la conexión que imprimió el script (la dirección privada se rellena sola), ponle nombre y, si quieres, región y etiquetas. La conexión se prueba antes de guardar nada; si podman no contesta, se dice por qué.

fundaia servers add madrid \
  --connection ssh://deploy@10.0.0.5/run/user/1000/podman/podman.sock \
  --address 10.0.0.5 --region eu-madrid --label ssd
fundaia servers list

Por MCP: add_server, list_servers, read_server. Los nombres local, rebalance, bootstrap y test están reservados.

Probar la conexión

Probar conexión, en el mismo diálogo, prueba una conexión sin guardar nada: si podman contesta, dice su versión, la máquina, sus CPUs y su memoria; si no, el error exacto y qué suele significar (la clave no está autorizada, esta máquina no conoce la huella SSH del servidor, nadie contesta en esa dirección y puerto, o podman no escucha en ese socket).

fundaia servers test ssh://deploy@10.0.0.5/run/user/1000/podman/podman.sock

Por MCP: test_server_connection. La orden sale con el código 9 cuando la conexión falla.

Cada 30 segundos se mide cada servidor (memoria libre, CPUs, disco, contenedores, versión de podman). Un servidor que deja de contestar se marca No responde: sus servicios no se dan por caídos mientras tanto, y vuelve a Listo solo en cuanto contesta.

Métricas de cada servidor

Cada medida se guarda, una fila por servidor y minuto, durante siete días: la memoria en uso (el pico del minuto), el disco, los contenedores en marcha y la CPU de sus contenedores (la suma de lo que miden sus servicios, sobre las CPUs de la máquina: podman solo da la media desde que arrancó). Métricas, en la tarjeta de cada servidor, las dibuja para la última hora, el último día (un punto cada cinco minutos) o la última semana (uno por hora), y se actualizan solas con cada medida.

fundaia servers metrics madrid --range 24h

Por MCP: read_server_metrics; por REST, GET /api/infra/servers/madrid/metrics?range=7d.

Etiquetas

Un servidor lleva etiquetas: ssd, gpu=a100, region=eu… Una clave lleva un solo valor (region=us sustituye a region=eu), y la región de un servidor cuenta como region=<región>. Se ponen en su tarjeta (Etiquetas), al añadirlo, o:

fundaia servers label madrid region=eu ssd
fundaia servers label madrid --rm ssd

Un entorno puede pedir etiquetas (Editar proyecto → Entornos → Dónde corre cada entorno, Qué etiquetas pide):

fundaia env require tienda production region=eu
fundaia env require tienda production --clear

Desde entonces solo va a servidores que las llevan todas: ssd vale con cualquier valor, region=eu solo con ese. Su primera colocación, una mudanza, un drenaje, la conmutación automática y el equilibrado lo respetan, y mudarlo a un servidor que no las lleva se rechaza diciendo cuáles le faltan. Si ningún servidor las lleva, su primer despliegue falla y lo dice. Pedirlas no lo muda: si su servidor no las lleva, el panel lo avisa y lo mudas tú.

Por MCP: label_server y require_server_labels.

Mudar un entorno

En Editar proyecto → Entornos → Dónde corre cada entorno, elige el servidor de destino, o:

fundaia env move tienda staging --to madrid --wait
fundaia env server tienda staging

Por MCP: move_environment y read_environment_server.

  1. Los servicios con volumen se paran en el origen y sus datos se copian al destino.
  2. El entorno pasa a vivir en el destino.
  3. Cada servicio desplegado se vuelve a desplegar allí desde el mismo commit o la misma imagen, primero los que otros usan. Los servicios sin datos siguen contestando desde el origen hasta que la versión del destino está sana: la mudanza no corta peticiones.
  4. Los contenedores del origen se drenan y se paran, y sus volúmenes se borran.

Si un servicio no llega a funcionar en el destino, la mudanza termina como fallida y dice cuál; los demás quedan ya en el destino. Vuelve a lanzarla, o múdalo de vuelta.

Acordonar y drenar

  • Acordonar un servidor (fundaia servers cordon madrid, cordon_server) hace que no reciba entornos nuevos. Lo que ya corre allí sigue. Reanudar (uncordon) lo deshace.
  • Drenar (fundaia servers drain madrid, drain_server) lo acordona y muda todos sus entornos, de uno en uno, al servidor con más memoria libre. --dry-run enseña el plan sin mover nada.
  • Quitar un servidor (fundaia servers rm madrid --confirm madrid, remove_server) solo se puede cuando está vacío. La máquina no se toca.

Equilibrar

Con el tiempo un servidor se llena y otro se queda vacío. Equilibrar (botón en Servidores) propone mover entornos sin volúmenes del servidor con más memoria en uso al que tiene más sitio, de uno en uno, hasta que la diferencia entre los dos baje del umbral (15 puntos por defecto). Nunca a un servidor acordonado o que no responde, siempre a uno con las etiquetas que pide cada entorno, y lo que solo corre en la principal se queda en ella. El tamaño de cada entorno es lo que miden ahora sus servicios: un entorno sin medidas recientes no se mueve.

El botón enseña el plan antes de mover nada.

fundaia servers rebalance                  # el plan
fundaia servers rebalance --apply          # y las mudanzas, de una en una
fundaia servers rebalance --threshold 25

Por MCP: rebalance_servers (dryRun: true para el plan). No se equilibra mientras haya una mudanza en curso.

Conmutación automática

Si un servidor pasa cinco minutos sin responder, sus entornos sin volúmenes se vuelven a desplegar en el servidor con más memoria libre, desde el mismo commit o la misma imagen, y la pasarela los sirve desde allí en cuanto están sanos. Los entornos con datos esperan a que el servidor vuelva: moverlos sin sus volúmenes sería arrancar con una base de datos vacía. El historial del proyecto lo apunta como sacó de un servidor caído el entorno.

Cuando el servidor vuelve, sus contenedores viejos ya no pertenecen a ningún despliegue vivo y se retiran solos. Está activada por defecto; se apaga por servidor con el interruptor de su tarjeta, fundaia servers failover madrid off o update_server.

Réplicas repartidas

Un servicio con réplicas puede tenerlas en servidores distintos: con Repartir las réplicas entre servidores (o --spread-replicas true), cada réplica va a otro servidor listo, el más holgado primero, y vuelve a la principal cuando ya hay una en cada uno. La pasarela reparte el tráfico entre todas, y si un servidor cae las réplicas de los demás siguen contestando.

fundaia settings tienda web --replicas 3 --spread-replicas true
fundaia replicas tienda web

Solo vale para servicios que no usan otros del entorno (un frontend, una API que habla con servicios de fuera): la red privada no cruza servidores, así que una réplica en otro servidor no llegaría a postgres:5432. Si el servicio usa otro, sus réplicas se quedan juntas en el servidor de su entorno y el despliegue lo dice.

Las imágenes viajan entre servidores

Una imagen construida vive en el servidor que la construyó. Cuando otro servidor la necesita, la plataforma la lleva (podman save en uno, podman load en el otro, pasando por la principal):

  • Promover entre dos entornos que viven en servidores distintos funciona igual que en uno.
  • Volver atrás a una versión anterior a una mudanza trae su imagen del servidor de origen, mientras ese servidor la conserve.
  • Una réplica repartida recibe la imagen antes de arrancar; las de un registro se descargan allí.

Lo que se queda en la principal

  • Los componentes de Claude Code: su imagen se construye y se actualiza en la principal.
  • Los componentes con fichero de configuración (Traefik, KrakenD): lo montan desde la principal.
  • Los contenedores adoptados.
  • Los workflows, que se ejecutan en la principal.

Un entorno con alguno de ellos no se coloca ni se muda a otro servidor, y se dice por qué.

Límites conocidos

  • Volver a una versión anterior a una mudanza necesita que el servidor de origen conserve su imagen (se guardan las dos últimas de cada servicio); si ya no está, despliega de nuevo ese commit.
  • Las construcciones ocupan las mismas dos plazas en toda la instancia, aunque se hagan en servidores distintos.
  • La conmutación automática solo mueve entornos sin datos; los que tienen volúmenes esperan a que su servidor vuelva, porque sus datos solo están allí (las copias de seguridad sí están en la principal: se pueden restaurar en un entorno nuevo).
  • Una copia de un entorno no hereda las etiquetas que pide el original: pídelas también en la copia.
  • Equilibrar solo mira la memoria en uso, y nunca mueve entornos con volúmenes: esos se mudan a mano.