Conceptos

Town OS está construido en torno a un conjunto de ideas centrales. Entender estos conceptos te ayudará a ver cómo encaja todo — desde definir un paquete hasta gestionar un servicio en marcha.

Paquetes

Un paquete es una definición YAML autocontenida de un servicio, tomada de un repositorio git. Cada paquete especifica sus asignaciones de puertos de red, sus volúmenes de almacenamiento, sus variables de entorno y sus preguntas interactivas — todo lo necesario para ejecutar el servicio. Los paquetes pueden ejecutarse como contenedores (lo predeterminado), como máquinas virtuales basadas en QEMU o como aplicaciones de Windows mediante la capa de compatibilidad Proton de Valve. Las plantillas de ficheros (ficheros text/template de Go) pueden generarse dentro de los volúmenes durante la instalación para lograr configuraciones dinámicas. Los paquetes declaran etiquetas supplies (como http, database, cache) para describir sus capacidades. El repositorio predeterminado incluye paquetes curados que cubren alojamiento de git, videoconferencias, streaming multimedia, mensajería de equipo y bases de datos — y se añaden más de forma constante.

Preguntas

Al instalar un paquete, Town OS puede mostrarte unos mensajes interactivos llamados preguntas. Tus respuestas rellenan los marcadores de plantilla @variable@ repartidos por toda la definición del paquete — fijando nombres de host, puertos, credenciales y otras opciones. Cada pregunta tiene un validador con tipo (hostname, port, bytes, volume, archive, duration, secret, boolean, oauth o texto libre) y un valor predeterminado opcional, de modo que los errores de configuración se detectan antes de que el servicio llegue a arrancar. El tipo también determina el control que ves — un boolean es una casilla, un secret es un campo enmascarado, y una pregunta oauth es un botón de Conectar que te identifica ante el proveedor y guarda el token que este devuelve. Varios tipos generan valores solos cuando los dejas vacíos: los puertos se asignan al azar en el rango 10000–60000, los nombres de host se generan como nombre-del-paquete-4hex, y los secretos producen una cadena hexadecimal de 64 caracteres. Una pregunta marcada como optional simplemente puede dejarse en blanco — un relay SMTP que no tienes se queda sin definir en lugar de rellenarse con una suposición.

Servicios

Una vez instalado, un paquete se convierte en un servicio — un contenedor en marcha gestionado por una unidad de systemd. Town OS te da control de arranque, parada y reinicio, transmisión de registros en vivo mediante Server-Sent Events, paginación del journal basada en cursores, y la posibilidad de habilitar o deshabilitar servicios. Los servicios están aislados entre sí y del sistema anfitrión.

Red

Town OS incluye rolodex, un servidor DNS que gestiona las zonas autoritativas de tus paquetes y reenvía las consultas al exterior. Cada paquete declara sus propias asignaciones de puertos — los puertos external quedan expuestos al anfitrión y los internal solo están disponibles entre contenedores. Los valores de los puertos admiten plantillas @variable@, así que el usuario puede elegir los puertos durante la instalación. Los paquetes que declaran dependencias comparten una red, lo que permite que los contenedores del mismo árbol de dependencias se comuniquen directamente. Los paquetes padre pueden referirse a sus dependencias con las variables de plantilla @dep_KEY_host@ y @dep_KEY_port_N@ en su entorno, o mediante variables de entorno en tiempo de ejecución (TOWNOS_DEP_{KEY}_HOST y TOWNOS_DEP_{KEY}_PORT_{port}). La redirección por UPnP se gestiona sola.

Redes

Una red es una superposición WireGuard con nombre, emparejada con un TLD de DNS. Los paquetes se instalan en una red, los pares se unen a ella y el TLD decide quién puede resolver qué. La red home siempre existe, no se puede eliminar y es solo de DNS: no tiene túnel, y el enrolamiento de pares en ella se rechaza, porque toda cuenta ya pertenece a ella y la mera pertenencia no debería ser una forma de entrar en un túnel. Las demás redes obtienen una interfaz WireGuard y una subred derivada de la identidad del propio ordenador, de modo que un dispositivo que se une a dos ordenadores Town OS nunca ve una colisión. Deshabilitar una red solo tira abajo el transporte: el acceso remoto se corta, mientras el DNS local y los contenedores siguen ejecutándose.

Ingress

Una única puerta de entrada compartida. Una sola instancia de Caddy retiene :443 y :80 para todo el ordenador y selecciona a qué servicio llegas puramente por SNI y Host — no hay escuchas por servicio ni directivas bind, así que un cliente de la LAN y un par de la superposición llegan al mismo socket, obtienen el mismo certificado y se redirigen al mismo contenedor. El nombre de un paquete es una sola cadena usada de cuatro maneras a la vez: el registro A, el SAN del certificado, el propietario del TLSA y el vhost del ingress.

TLS y la autoridad certificadora local

Town OS ejecuta su propia autoridad certificadora y emite certificados para los nombres que reclaman tus paquetes, de modo que los servicios quedan accesibles por HTTPS sin un certificado público ni una advertencia del navegador. El certificado de la CA se descarga desde /tls/ca.crt: confiar en él una vez es lo que hace funcionar todos los nombres locales. Los certificados se renuevan en segundo plano en lugar de al arrancar, y un cambio de TLD reemite los nombres que dependen de él.

Almacenamiento de objetos

Town OS incorpora almacenamiento de objetos mediante gfeh. Una partición es un subvolumen btrfs con su propio demonio y su propio conjunto de usuarios, y hay exactamente una por red, así que un usuario, un permiso o un enlace publicado en una red no significan nada en otra. Cada partición sirve cuatro vistas: S3, HTTP simple, un explorador tipo unidad e IPFS. Los usuarios son principales dispuestos en un árbol; el acceso es una concesión, siempre recortada al techo del principal al que se otorga; y un enlace publicado es una exposición que después puede retirarse. Ninguna partición publica un puerto del anfitrión — el ingress llega a cada una por el nombre del contenedor.

Almacenamiento

Todos los datos se guardan en subvolúmenes btrfs con aislamiento por paquete. Cada volumen tiene un punto de montaje dentro del contenedor, una cuota configurable (por ejemplo 512mb, 2gb) y, opcionalmente, propietario por uid/gid. Los volúmenes pueden rellenarse de antemano desde imágenes de contenedor con la función archives, o inicializarse clonando un repositorio git dentro de un volumen vacío durante la instalación. Los usuarios también pueden crear sus propios volúmenes independientes. Las imágenes de disco de las máquinas virtuales se guardan en caché en un subvolumen dedicado, de modo que las instalaciones posteriores las reutilizan. Se admiten instantáneas de btrfs para copias de seguridad puntuales. Los datos sobreviven a reinstalaciones y actualizaciones de paquetes — tus ficheros nunca se pierden al actualizar un servicio.

Repositorios

Los paquetes se organizan en repositorios — repos de git con un directorio packages/ que contiene definiciones YAML versionadas. Toda instalación de Town OS incluye el repositorio predeterminado, pero cualquiera puede crear y compartir repositorios propios. Los repositorios están ordenados — las entradas posteriores prevalecen sobre las anteriores cuando los nombres de paquete chocan. Un fichero featured.json puede destacar ciertos paquetes en la interfaz.

Plantillas y notas

El sistema de plantillas @variable@ conecta las respuestas del usuario con las variables de entorno, las asignaciones de puertos, las cuotas de los volúmenes y más. Variables integradas como @LOCAL_EXTERNAL_HOST@ y @LOCAL_INTERNAL_HOST@ están siempre disponibles. Ya instalado, las notes muestran datos clave como URLs de conexión, credenciales o información de contacto — con validación de tipo opcional para url, phone y email.

Páginas

Town OS puede alojar sitios web estáticos. Cada página admite tres orígenes posibles: subir un fichero tar, extraer ficheros de una imagen de contenedor o clonar un repositorio git. Cada página obtiene su propio dominio y se sirve a través de Caddy. Las páginas de tipo fichero comprimido se actualizan volviendo a subirlo; las de git y de imagen de contenedor pueden reconstruirse cuando quieras.

Monitorización

Un conjunto de observabilidad integrado funciona de serie, sin configuración alguna. Prometheus recolecta métricas y Node Exporter informa de las estadísticas del anfitrión (CPU, memoria, disco, red). Hay dos backends de monitorización disponibles: una interfaz integrada y ligera (la predeterminada) o Grafana con paneles aprovisionados automáticamente. Todo el conjunto se ejecuta como servicios del sistema y se reinicia solo si algo falla.

Internacionalización

Todas las cadenas de texto que ve el usuario pasan por un catálogo de mensajes indexado por códigos de idioma BCP 47. Se presentan 21 idiomas comunes en su propia escritura, con más de 87 códigos específicos por país disponibles. Hoy solo el inglés (en-US) está traducido por completo — la infraestructura ya está lista para las traducciones de la comunidad.

Cuentas y sesiones

Town OS admite cuentas de administrador y de usuario normal. Las contraseñas requieren un mínimo de 8 caracteres. La autenticación usa tokens JWT que caducan a los 7 días de inactividad. Las sesiones son efímeras — las claves de firma se regeneran en cada reinicio, lo que borra todas las sesiones activas de forma automática.

Registro de auditoría

Cada acción administrativa queda registrada con el nombre de la cuenta, la acción, la ruta de la petición, el detalle, un indicador de éxito y la marca de tiempo. Los endpoints de solo lectura quedan fuera. El registro de auditoría admite paginación, filtrado por cuenta y búsqueda de texto completo.

Ajustes

La configuración de todo el sistema se gestiona con ajustes de clave y valor desde la interfaz. Entre los valores configurables están la cuota predeterminada de los volúmenes (50 GB), el tamaño máximo de fichero subido (1 GB), el tiempo límite para descomprimirlo (600 s), el idioma, la imagen del ejecutor de Proton y el dominio de nivel superior del DNS.

Actualizaciones de paquetes

Town OS detecta solo cuándo hay versiones más nuevas de un paquete en los repositorios que tengas configurados. Una insignia en el panel muestra cuántas actualizaciones están pendientes. Puedes descartar las versiones que no quieras — los descartes se registran con un hash SHA256, así que solo reaparecen cuando cambia el conjunto de actualizaciones.

Servicios del sistema

Los contenedores de infraestructura — monitorización, DNS y la interfaz web — se gestionan aparte de los paquetes que instala el usuario. Usan un prefijo de systemd distinto (town-os-system--), siempre se reinician si fallan y los usuarios no pueden deshabilitarlos.