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 administrar 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 correr el servicio. Los paquetes pueden correr 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 archivos (archivos text/template de Go) pueden generarse
dentro de los volúmenes al momento de instalar 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
hospedaje de git, videoconferencias, streaming multimedia, mensajería de equipo
y bases de datos — y se agregan más de forma constante.
Preguntas
Al instalar un paquete, Town OS puede mostrarte unos mensajes interactivos llamados
preguntas. Tus respuestas llenan 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, así que los errores de configuración se detectan antes de que el servicio
arranque siquiera. 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 da de alta con 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 relevo SMTP que no
tienes se queda sin definir en lugar de llenarse con una suposición.
Servicios
Una vez instalado, un paquete se convierte en un servicio — un contenedor en marcha administrado por una unidad de systemd. Town OS te da control de arranque, paro 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 administra 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 al instalar. 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}). El reenvío por UPnP se maneja solo.
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 simple membresía no debería
ser una manera de entrar a un túnel. Las demás redes obtienen una interfaz
WireGuard y una subred derivada de la identidad de la propia computadora, así que un
dispositivo que se une a dos computadoras Town OS nunca ve una colisión. Deshabilitar
una red solo baja el transporte: el acceso remoto se corta, mientras el DNS local y
los contenedores siguen corriendo.
Ingress
Una sola puerta de entrada compartida. Una única instancia de Caddy se queda con
:443 y :80 para toda la computadora y elige 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 enrutan 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 dueño del TLSA y el vhost del ingress.
TLS y la autoridad certificadora local
Town OS corre su propia autoridad certificadora y emite certificados para los
nombres que reclaman tus paquetes, así 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 trae almacenamiento de objetos por medio de 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 ordenados en un árbol; el acceso es una concesión, siempre recortada al techo del principal al que se le da; y un enlace publicado es una exposición que después se puede retirar. 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, dueño por
uid/gid. Los volúmenes pueden llenarse de antemano desde
imágenes de contenedor con la función archives, o sembrarse clonando un
repositorio git dentro de un volumen vacío al instalar. 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
respaldos puntuales. Los datos sobreviven a reinstalaciones y actualizaciones de
paquetes — tus archivos 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 le ganan a las anteriores cuando los nombres de paquete chocan. Un
archivo 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 hospedar sitios web estáticos. Cada página admite tres orígenes posibles: subir un archivo tar, extraer archivos 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 archivo se actualizan volviendo a subirlo; las de git y de imagen de contenedor pueden reconstruirse cuando quieras.
Monitoreo
Un conjunto de observabilidad integrado funciona de fábrica, sin configuración alguna. Prometheus recolecta métricas y Node Exporter reporta las estadísticas del anfitrión (CPU, memoria, disco, red). Hay dos backends de monitoreo disponibles: una interfaz integrada y ligera (la predeterminada) o Grafana con paneles aprovisionados automáticamente. Todo el conjunto corre 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 llaves de firma se regeneran en cada reinicio, lo que borra todas las sesiones activas de forma automática.
Bitácora 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. La bitácora de auditoría admite paginación, filtrado por cuenta y búsqueda de texto completo.
Ajustes
La configuración de todo el sistema se administra 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 archivo 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 rastrean con un hash SHA256, así que solo reaparecen cuando cambia el conjunto de actualizaciones.
Servicios del sistema
Los contenedores de infraestructura — monitoreo, DNS y la interfaz web — se
administran 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.