Guía del usuario

Construir la imagen USB desde el código

La imagen USB de Town OS se construye desde el repositorio install. El proceso produce una imagen arrancable con un sistema de archivos raíz squashfs y un esquema de particiones GPT.

Requisitos previos

Necesitas un anfitrión con Linux y una memoria USB (de 4 GB o más). La construcción usa herramientas de Arch Linux (pacstrap, mkinitcpio, arch-chroot), pero no hace falta que corras Arch — en cualquier otra distribución, make image ejecuta la construcción dentro de un contenedor de Arch de la misma arquitectura. Instala las dependencias del anfitrión con el objetivo que corresponda a tu distribución:

• make deps — Arch (y derivadas) o Fedora/RHEL
• make deps-debian — Debian o Ubuntu

Esos objetivos traen todo lo que necesitan la construcción y las herramientas de máquinas virtuales — make, podman, arch-install-scripts, squashfs-tools, parted, e2fsprogs, dosfstools, qemu y libvirt.

Clonar y construir

git clone https://gitea.com/town-os/install.git
cd install
make image

Correr make o make image construye la imagen USB completa. El proceso descarga el sistema base, instala los componentes de Town OS, comprime todo en un sistema de archivos squashfs y arma la imagen de disco final con una tabla de particiones GPT.

Particionado y squashfs

La imagen resultante usa un esquema GPT con:

• Una partición de arranque BIOS (1 MiB) para el arranque BIOS clásico
• Una partición de sistema EFI (64 MiB, FAT32) para el arranque UEFI
• Una partición de datos (ext4) que contiene el sistema de archivos raíz squashfs y GRUB

Al arrancar, Town OS monta el squashfs como capa inferior de solo lectura, con una capa tmpfs encima. Eso significa que el sistema operativo corre por completo en RAM — la memoria USB solo se lee al arrancar. Todos los cambios en tiempo de ejecución ocurren en memoria y se descartan al reiniciar, dejándote la pizarra limpia cada vez.

Grabar la imagen

Lo más sencillo es make flash, que construye la imagen si está desactualizada y la graba en un dispositivo USB. Si prefieres hacerlo a mano, ten en cuenta que la construcción produce un archivo con la fecha y el sufijo de arquitectura (por ejemplo town-os-2026-07-25-x86_64.img) — grábalo con dd:

# Encuentra tu dispositivo USB (por ejemplo /dev/sdb)
lsblk

# Graba la imagen (cambia el nombre del archivo y /dev/sdX por tu dispositivo)
sudo dd if=town-os-YYYY-MM-DD-x86_64.img of=/dev/sdX bs=4M status=progress conv=fsync

Verifica dos veces el dispositivo de destino — dd sobrescribe lo que sea que le apuntes, sin pedir confirmación.

Configurar el DNS en tu router

Town OS incluye rolodex, un servidor DNS que administra las zonas autoritativas de tus paquetes y reenvía las consultas al exterior. Para usarlo como servidor DNS de tu red, tienes que decirle a tu router que reparta la dirección IP de la máquina con Town OS como servidor DNS. Así, cada dispositivo de tu red usa rolodex automáticamente — sin configurar nada equipo por equipo.

Encuentra la dirección IP de Town OS

Vas a necesitar la dirección IP local de tu máquina con Town OS. Puedes encontrarla así:

• Entra al panel en http://town-os.local después de la configuración inicial y toma la IP interna que aparece ahí — esa es la dirección que debes usar como servidor DNS
• Corre make vm-ip si estás usando una máquina virtual
• Busca en la lista de clientes DHCP de tu router un dispositivo llamado «town-os»

Para que el DNS funcione de forma confiable, tu máquina con Town OS debería tener una dirección IP fija o una reserva DHCP en el router. Si la IP cambia, el DNS se rompe para toda tu red.

Asigna una IP fija o una reserva DHCP

Casi todos los routers permiten reservar una dirección IP para un dispositivo concreto según su dirección MAC. Normalmente está en Configuración LAN, DHCP o Reserva de direcciones. Busca la máquina con Town OS en la lista de clientes y reserva la IP que tiene ahora.

Si tu router no admite reservas DHCP, puedes configurar una IP fija en la propia máquina con Town OS agregándola a town-os.yaml.

Cambia el servidor DNS en tu router

Los pasos exactos varían según la marca del router, pero el proceso general es el mismo:

1. Entra a la interfaz de administración de tu router (normalmente 192.168.1.1 o 192.168.0.1)
2. Busca la sección Configuración DHCP, Configuración LAN o Configuración DNS
3. Cambia el servidor DNS primario por la dirección IP de tu máquina con Town OS
4. Si quieres, pon un servidor DNS secundario como respaldo (por ejemplo 1.1.1.1 u 8.8.8.8) — se usará cuando Town OS no esté disponible
5. Guarda y aplica la configuración

Después de guardar, los dispositivos de tu red tomarán el nuevo servidor DNS la próxima vez que renueven su concesión DHCP. Puedes forzarlo desconectándote y volviéndote a conectar a la red, o reiniciando el dispositivo.

Interfaces de routers comunes

Desactiva el DNS del navegador

La mayoría de los navegadores traen su propio resolvedor de DNS y se saltan tu router por completo. El DNS sobre HTTPS (DoH) de Firefox y las funciones equivalentes de «DNS seguro» en Chrome y Edge mandan las consultas directo a un proveedor público como Cloudflare o NextDNS, así que Town OS nunca ve la consulta y los nombres de tus paquetes regresan como «servidor no encontrado», aunque el resto de la red los resuelva sin problema. Desactívalo en cada dispositivo que deba llegar a tus servicios por nombre:

• Firefox — Configuración → Privacidad y seguridad → DNS sobre HTTPS, elige Desactivado. (La protección predeterminada también puede activar DoH en silencio, así que elige «Desactivado» en lugar de dejar el valor por omisión.)
• Chrome — Configuración → Privacidad y seguridad → Seguridad, desactiva Usar DNS seguro.
• Edge — Configuración → Privacidad, búsqueda y servicios → Seguridad, desactiva Usar DNS seguro para especificar cómo buscar la dirección de red de los sitios web.
• Brave, Vivaldi, Opera — la misma opción que en Chrome, bajo Privacidad y seguridad → Seguridad.
• Safari — no trae DoH propio; usa el resolvedor del sistema. Verifica que no haya un perfil de DNS instalado en Configuración del sistema → General → VPN, DNS y administración de dispositivos.

Lo mismo aplica a cualquier DNS cifrado que hayas configurado a nivel de sistema — el DNS privado de Android, los perfiles DNS de iOS/macOS, o una configuración local de systemd-resolved/dnscrypt. Cualquiera de ellos anula el servidor DNS que reparte tu router. Si quieres DNS cifrado hacia el exterior, déjaselo a Town OS: rolodex puede usar DoH/DoT hacia arriba mientras sigue respondiendo tus nombres locales (ve Elegir un modo de resolución más abajo).

Verifica que funcione

Cuando tu dispositivo tome la nueva configuración de DNS, verifica que rolodex esté atendiendo tus consultas:

# Revisa qué servidor DNS está usando tu máquina
nslookup example.com

# O consulta directo a Town OS
dig @<ip-de-town-os> example.com

# Consulta un dominio de paquete (si ya tienes paquetes instalados).
# Los nombres siguen el patrón <nombre>.<repo>.<tld> — .home es el TLD de la red predeterminada
dig @<ip-de-town-os> gitea.default.home

Si example.com se resuelve correctamente, rolodex está funcionando y atendiendo el DNS de tu red.

Elegir un modo de resolución

Los nombres que no pertenecen a ninguna de tus redes se resuelven según el modo de resolución, que configuras en Ajustes → Resolución DNS dentro del panel. Hay tres modos:

• Automático (recomendado) — el predeterminado. Primero intenta resolver de forma iterativa desde los servidores raíz, y si falla va cayendo a DoH/DoT, a un reenviador local y por último a un resolvedor público, quedándose con el nivel que funcionó la última vez. Así conserva la privacidad de la recursión donde la red lo permite y se degrada con elegancia en redes que filtran el DNS saliente.
• Solo recursivo — resuelve todo de forma iterativa desde los servidores raíz, sin alternativas. Garantiza que ninguna consulta se le entregue a un resolvedor de terceros, pero todos los nombres externos fallan en redes que bloquean o secuestran el puerto 53 saliente (hoteles, portales cautivos, algunos ISP).
• Reenvío — siempre manda las consultas que no coinciden a resolvedores externos (Google Public DNS por omisión). Es el comportamiento clásico de reenvío.

Ten en cuenta que este ajuste trata de cómo la computadora llega a internet. El DNS cifrado en la otra dirección — el que usan tus propios dispositivos para llegar a la computadora — se ve a continuación.

DNS cifrado desde tus dispositivos

Town OS sirve DNS cifrado a tus propios dispositivos, no solo para sí mismo. Hay tres extremos disponibles, y todos responden por los mismos nombres que el DNS simple del puerto 53:

• DNS sobre HTTPS (DoH) — https://dns.<tld>/dns-query. Este pasa por el ingress en el puerto HTTPS estándar, y por eso es el que tiene más probabilidades de funcionar en una red restrictiva.
• DNS sobre TLS (DoT) — dns.<tld> en el puerto 853.
• DNS sobre QUIC (DoQ) — dns.<tld> en el puerto 853 sobre UDP.

Los tres presentan un certificado emitido por la autoridad certificadora de tu propia computadora, con el mismo nombre y las mismas direcciones que usa el resto del sistema. Si ya instalaste la CA raíz en el dispositivo (ve Confiar en la autoridad certificadora), se validan sin nada más que configurar.

Un dispositivo que nunca ha confiado en tu CA también puede verificar estos extremos. Town OS publica registros DANE que fijan el certificado en la zona de la que es autoritativo, bajo _853._tcp.dns.<tld> y _853._udp.dns.<tld> — uno por cada transporte, porque un cliente que entiende DANE y no encuentra registro para el transporte que eligió falla cerrado. Como el dispositivo puede llegar al resolvedor, puede bajar la fijación, y así puede comprobar lo que le entregan sin instalar nada antes.

Los clientes compatibles con DDR encuentran todo esto solos. Town OS publica un registro de designación en _dns.resolver.arpa (RFC 9462) que nombra la URL de DoH y los puertos de DoT y DoQ, en ese orden de preferencia — DoH primero, porque el puerto 443 sobrevive al filtrado que bloquea el 853. Un dispositivo con DDR apuntado a tu computadora para DNS común descubre el extremo cifrado y se pasa a él por su cuenta.

Estas tres escuchas se abren desde la configuración de la imagen de instalación al arrancar, así que, a diferencia de casi todos los ajustes de DNS, no se activan desde el panel. El certificado que hay detrás se renueva en segundo plano mientras la computadora simplemente está encendida — sin reiniciar — y la nueva fijación DANE se publica antes de retirar la anterior, de modo que no hay ningún momento en que un cliente que valida rechazaría la conexión.

Bloquear dominios maliciosos

rolodex puede filtrar cada consulta contra listas de bloqueo públicas, dándote bloqueo de amenazas para toda la red sin necesidad de un Pi-hole aparte. Esto se administra en DNS → Listas de bloqueo. Hay dos clases de proveedor, y actúan sobre cosas distintas:

• DNSBL (lista de bloqueo de dominios) — coincide con el nombre que se está consultando. Este es el lado que afecta la navegación normal.
• RBL (Realtime Blackhole List) — coincide con una dirección IP, y solo en las consultas de DNS inverso.

Ambos vienen desactivados y con la lista de proveedores vacía, y ambos se consultan sobre la marcha: Town OS nunca descarga, analiza ni guarda en caché por adelantado una lista de bloqueo. No se revisa nada hasta que enciendes una categoría y agregas al menos una zona.

Cómo funciona una consulta DNSBL

El nombre que se está resolviendo se antepone a la zona del proveedor y se consulta como una petición DNS normal. Resolver badsite.example con dbl.spamhaus.org activado dispara una consulta a badsite.example.dbl.spamhaus.org.

• Una respuesta significa que está listado — los proveedores contestan con un registro de dirección (normalmente 127.0.0.x) para un nombre listado. rolodex entonces devuelve NXDOMAIN al dispositivo que preguntó.
• NXDOMAIN significa limpio — la resolución sigue con normalidad. Un proveedor que da error o se agota por tiempo se trata como no listado, así que una lista de bloqueo inalcanzable nunca deja tu red sin conexión.
• Las listas de bloqueo le ganan al mundo exterior, nunca a tus propios registros — la revisión ocurre después de los registros locales y de paquetes (así que gitea.default.home siempre resuelve) pero antes de la caché externa y del reenviador, de modo que un nombre listado se rechaza aunque ya hubiera una respuesta reenviada en caché.
• La coincidencia es por nombre, no por sufijo — que doubleclick.net esté listado no bloquea stats.g.doubleclick.net, a menos que el proveedor también liste ese nombre. Tumbar un dominio entero por un solo host listado es una decisión tuya, no de la lista.
• Los resultados se guardan en caché un rato — un listado durante el TTL del proveedor, un resultado limpio durante cinco minutos.

Proveedores DNSBL

Estos son los que puedes agregar con un clic desde el panel. Todos siguen operando, son gratuitos y responden a un resolvedor que recursa por su cuenta sin ningún registro previo — que es justo lo que es un equipo con Town OS. También puedes escribir cualquier otra zona.

Cómo funciona una consulta RBL

La dirección IP se invierte y se antepone a la zona del proveedor. Revisar 192.168.1.100 contra zen.spamhaus.org dispara una consulta a 100.1.168.192.zen.spamhaus.org. Las direcciones IPv6 se expanden a nibbles y se invierten igual. Una respuesta significa listado, NXDOMAIN significa limpio, y los resultados se guardan en caché exactamente igual que los de DNSBL.

El detalle: las zonas RBL solo se consultan para las IPs que aparecen en consultas de DNS inverso (in-addr.arpa e ip6.arpa), y la navegación normal apenas genera de esas. Estas listas existen para que un servidor de correo rechace a un remitente que se conecta, y ahí es donde se ganan su lugar. En el router de una casa son prácticamente inútiles — el lado DNSBL de arriba es el que de verdad afecta la navegación. Actívalas si corres un servicio de correo detrás de Town OS; si no, las listas de dominios son las que merecen tu atención.

Proveedores RBL

Listas que a propósito no se ofrecen

Tres zonas conocidas quedan fuera de la lista de un clic a propósito, porque cada una falla en silencio — verías un proveedor configurado y darías por hecho que estás protegido. Aun así puedes agregarlas a mano si sabes lo que haces.

• SORBS (dnsbl.sorbs.net) — dada de baja el 5 de junio de 2024 y con sus zonas vaciadas. Responde, solo que nunca lista nada: una operación nula permanente que parece protección.
• Barracuda (b.barracudacentral.org) — gratis, pero exige registrar antes la IP que consulta. Un equipo sin registrar puede funcionar un rato y luego quedar cortado sin aviso.
• UCEPROTECT niveles 2 y 3 — listan bloques de red y ASN completos, así que un solo vecino problemático en tu ISP bloquea al ISP entero.

Entradas locales y listas de permitidos

• Entradas locales (DNS → Listas de bloqueo) — bloquea a mano un dominio o una IP concreta, con un motivo anotado al lado. Una entrada de dominio devuelve NXDOMAIN en las consultas directas y surte efecto de inmediato. Se revisa antes que cualquier proveedor externo, y es la forma de bloquear un host específico sin suscribirte a una lista entera.
• Listas de permitidos (DNS → Listas de permitidos) — tu salida de emergencia ante un falso positivo. Un nombre permitido se salta toda la revisión por nombre: no se compara ni con los proveedores DNSBL ni con tus entradas locales, y no se emite ninguna consulta al proveedor por él. A diferencia del bloqueo, permitir sí funciona por sufijo — exentar vendor.example también exenta cdn.vendor.example. Las entradas son solo nombres, nunca IPs, así que el camino de RBL por IP inversa queda intacto.

Qué esperar

Estas listas están hechas para el correo, no para la publicidad. Son excelentes con dominios de phishing, malware y carga útil de spam, y mediocres con anuncios y rastreadores — ese trabajo es territorio de las listas descargables tipo hosts, que Town OS deliberadamente no consume. No se descarga nada de forma programada, no se analiza nada y no se guarda nada en caché a tus espaldas. Si quieres que un dominio de anuncios o rastreo concreto desaparezca, agrégalo como entrada local.

Publicar servicios en el DNS

De forma predeterminada, cada servicio de un paquete instalado se publica en el DNS bajo el TLD de su red, para que puedas llegar a él por nombre. En DNS → Servicios puedes activar o desactivar la publicación de cada servicio — un servicio sin publicar sigue corriendo, pero deja de resolverse por nombre. El nombre completo de cada servicio sigue el patrón <nombre>.<repo>.<tld> (en la red predeterminada, ese TLD es .home).

Redes y acceso remoto

Town OS agrupa tus servicios en redes. Todo equipo empieza con una red integrada llamada home — es solo de red local, resuelve nombres bajo .home y no tiene túnel. Para llegar a tus servicios de forma segura desde fuera de casa, crea redes adicionales: cada una es una superposición WireGuard emparejada con su propio TLD de DNS, y se administra en Panel → Redes (solo administradores).

La red predeterminada

• Siempre está y no se puede quitar. La red home se crea sola y es donde caen los paquetes a menos que elijas otra.
• Solo local. No tiene transporte WireGuard — los nombres .home se resuelven en tu red local y a propósito nunca se exponen a los pares remotos.
• Usa el TLD .home, que viene del ajuste dns_tld.

Crear una red para acceso remoto

Haz clic en Crear red y dale un nombre (por ejemplo oficina) y, si quieres, un TLD (por omisión toma el nombre de la red). Entonces Town OS:

• Genera una interfaz WireGuard con una subred de superposición determinista sacada del rango 10.64.0.0/10, con el propio equipo en la dirección .1.
• Reclama el TLD de la red (los TLD son únicos por equipo — crear una red con un TLD que ya tiene otra se rechaza).
• Corre un resolvedor DNS por red sobre la superposición, para que los dispositivos conectados puedan resolver los nombres de esa red.

El interruptor de acceso remoto de cada fila levanta o baja la interfaz WireGuard. Apagarlo corta el acceso remoto pero deja los contenedores corriendo y accesibles en la red local.

Dar de alta un dispositivo

Abre el diálogo de Pares de una red, escribe el nombre del dispositivo y haz clic en Agregar par. Town OS te devuelve una configuración de WireGuard lista para importar — pégala en la app de WireGuard de tu celular o tu laptop.

Copia la configuración de inmediato. Contiene una llave privada recién generada que nunca se guarda — no puedes recuperarla después, y tendrás que dar de alta el dispositivo otra vez si la pierdes.

La configuración generada apunta el DNS del dispositivo a la dirección de superposición del equipo, así que los nombres de tu red se resuelven solos en cuanto el túnel está arriba. Deja apagado el interruptor Corre rolodex DNS para los dispositivos normales; enciéndelo solo para un par que a su vez corra un servidor DNS rolodex al que quieras reenviar.

Cuentas solo de WireGuard

Para dejar que alguien dé de alta sus propios dispositivos sin darle rienda suelta al panel, crea una cuenta solo de WireGuard (una casilla en la pantalla de Crear usuario). Una cuenta así:

• Está limitada a una o más redes concretas — solo puede dar de alta pares en esas, y nunca en la red home.
• Es restrictiva por diseño: puede autenticarse, dar de alta y renovar sus propios pares, y obtener la CA, pero nada más del plano de control.
• Da de alta pares que caducan. Cada alta trae un tiempo de vida (2 horas por omisión, ajustable en Ajustes → Tiempo de vida de pares WireGuard) y hay que renovarla para seguir conectado; los dispositivos abandonados caducan solos. Los pares que agrega un administrador son permanentes.

Vigilar y desconectar pares

El panel de Pares conectados en la página de Redes lista todos los pares dados de alta en todas las redes, con su estado de saludo en vivo, su IP de superposición, los datos transferidos y su caducidad. Para cortarle el paso a un dispositivo por la fuerza, usa Desconectar — eso quita el par, tira su túnel de inmediato y revoca su llave, así que el dispositivo no puede volver a conectarse hasta darlo de alta otra vez.

Instalar paquetes en una red

El diálogo de instalación (y el de Páginas) incluye un selector de Red. La red que elijas determina el nombre DNS del servicio y su certificado TLS — un paquete instalado en oficina se resuelve bajo .oficina y su certificado se emite para ese nombre. Los servicios en una red distinta de la predeterminada tienen doble domicilio: se resuelven a la dirección de superposición para los pares por túnel y a la dirección de red local para los clientes locales. Reinstalar un paquete en otra red mueve su DNS y sus certificados al TLD de esa red.

Por ejemplo, instalar Jitsi en una red con el TLD fart lo publica en jitsi.default.fart. Ya corriendo, el servicio aparece en tu Panel como un enlace en el que puedes hacer clic con esa dirección, listo para abrirse desde cualquier dispositivo de la red.

Armar máquinas virtuales desde imágenes USB

El repositorio install incluye scripts para levantar Town OS en máquinas virtuales, lo cual sirve para pruebas y desarrollo — ya sea desde una imagen que construiste tú o directamente desde una memoria USB física que ya grabaste. make help lista todos los objetivos y variables.

QEMU

make qemu-fg

Construye la imagen si está desactualizada y luego levanta una máquina virtual de QEMU en primer plano, con la consola serial conectada, aceleración por KVM y cuatro discos virtuales de datos para probar el almacenamiento. Este es el objetivo al que debes recurrir: ves el arranque y el instalador directo en tu terminal, y Ctrl-C detiene la máquina. Usa make qemu si prefieres que corra en segundo plano (conéctate después con make serial), y make rebuild-qemu para detener, limpiar, reconstruir y relanzar de un jalón.

La máquina virtual se conecta a la red NAT default de libvirt en virbr0 y queda fija en VM_IP (192.168.122.50 por omisión), así que dale su propia dirección a cada máquina que corras al mismo tiempo.

Como el huésped está detrás de NAT, VM_LAN=1 (el valor por omisión) retransmite la API de control (5309), la interfaz (80/443), ssh (2222) y los puertos UDP de WireGuard desde la dirección de red local del anfitrión hacia el huésped — eso es lo que permite que un celular con el cliente de Android llegue a una máquina virtual. Pon VM_LAN=0 para apagar esas retransmisiones.

Arrancar una USB física (qemu-usb)

make qemu-usb USB_DEV=/dev/sdX

Arranca QEMU en primer plano directamente desde una memoria USB física ya grabada, en vez de una imagen construida — práctico para confirmar que la memoria que acabas de grabar realmente arranca. El dispositivo se abre en solo lectura (instantánea), así que lo que escriba el huésped se descarta y la USB real nunca se modifica; los cuatro discos virtuales de datos siguen conectados para probar el almacenamiento. Este objetivo no construye nada — clona el repositorio install, graba una memoria con install.sh o make flash, y luego apunta USB_DEV hacia ella. En un anfitrión x86_64, TARGET=aarch64 (o rpi) arranca la memoria bajo emulación de sistema completo, así que puedes probar una imagen de otra arquitectura sin tener el hardware correspondiente.

Detener y limpiar

# Detén la máquina virtual
make stop

# Detén las máquinas virtuales y borra la imagen y los discos virtuales
make clean

Variables de entorno

Consola serial

# Conéctate a la consola serial de la máquina virtual
make serial

# O manualmente con socat
socat -,rawer,escape=0x1d unix-connect:/tmp/town-os-serial.sock

# Sal con Ctrl-]

Encontrar la máquina virtual

# Obtén la dirección IP de la máquina virtual
make vm-ip

# O conéctate por mDNS desde el anfitrión
ssh root@town-os.local

Instalación con RAID

El aprovisionamiento de discos lo hace de forma interactiva ttyforce durante el primer arranque. Todo el almacenamiento usa btrfs.

Selección automática del RAID

ttyforce detecta los discos disponibles, los agrupa por tipo de transporte (NVMe, SATA, etc.) y por tamaño similar, y luego elige automáticamente el nivel de RAID según cuántos discos haya:

• 1 disco — modo único (sin redundancia)
• 2 discos — RAID 1 (espejo de btrfs)
• 3 o más discos — RAID 5 (btrfs con paridad distribuida)

El punto de montaje por omisión es /town-os. ttyforce crea los subvolúmenes @etc y @var para la persistencia compatible con overlayfs.

Detección de discos

ttyforce detecta solo los dispositivos de almacenamiento disponibles. Identifica discos NVMe, discos SATA/SAS y tarjetas SD, y excluye el dispositivo USB de arranque y cualquier medio extraíble. La lógica de detección garantiza que Town OS nunca toque el disco desde el que arrancó.

Sistema de archivos superpuesto

Sin importar el backend de almacenamiento, Town OS usa montajes superpuestos para la persistencia de /var y /etc. La capa inferior viene de la raíz squashfs, mientras que la superior vive en el almacenamiento RAID/ZFS. Así, la configuración del sistema y los datos de los servicios sobreviven a los reinicios mientras el sistema operativo base se mantiene inmutable.

Hospedar sitios estáticos

Más allá de los paquetes en contenedores, Town OS trae hospedaje de sitios estáticos integrado, siempre encendido y administrado en Panel → Páginas. Cada página la sirve un servidor web compartido detrás de la entrada, y obtiene un nombre DNS y un certificado TLS bajo el TLD de su red, igual que un paquete.

Orígenes del contenido

Al crear una página eliges un nombre, un dominio (por omisión, el nombre), una red (por omisión home) y uno de tres orígenes de contenido:

• Subir un archivo — sube un tarball de tu sitio. La página se queda pendiente hasta que lo subas.
• Repositorio git — clona desde la URL de un repo. Puedes indicar una rama (por omisión main), lo cual es cómodo para sitios publicados en gh-pages.
• Imagen de contenedor — extrae un directorio de una imagen OCI.

Las páginas de git y de contenedor se preparan de forma asíncrona — la tabla muestra una insignia de Preparando… que termina en activa o en error. Usa Reconstruir para traer el contenido más reciente en las páginas de git y de contenedor; en una página de archivo, sube un tarball nuevo.

Cómo se sirven las páginas

Cada página vive en su propio subvolumen de almacenamiento y se sirve directamente por HTTP en el puerto 80, mientras que los servicios de los paquetes redirigen el puerto 80 a HTTPS. Como una página lleva una red, su nombre se resuelve bajo el TLD de esa red y está accesible desde tu red local y — si la red es una superposición WireGuard — desde tus dispositivos remotos dados de alta.

Crear un paquete

Los paquetes de Town OS son archivos YAML que describen cómo correr un servicio en contenedor. Para la especificación completa, ve la referencia del formato de empaquetado. Esta sección cubre el flujo práctico.

Estructura del repositorio

Un repositorio de paquetes es un repositorio git con un directorio packages/. Cada paquete tiene su subdirectorio con definiciones YAML versionadas:

my-packages/
  packages/
    my-app/
      1.0.yaml
      2.0.yaml

Escribir la definición de un paquete

Un paquete mínimo solo necesita un campo image. Un paquete típico incluye además una descripción, red, volúmenes y preguntas para el usuario:

image: myapp:latest
description: My custom application
supplies: ["http"]
network:
  external:
    "@port@": "8080"
volumes:
  data:
    mountpoint: /app/data
    quota: 5gb
questions:
  port:
    query: "What external port should this app use?"
    type: port
    default: "9000"
notes:
  URL:
    value: "http://@LOCAL_EXTERNAL_HOST@:@port@"
    type: url

Las preguntas admiten varios tipos más allá del texto libre y de port: secret (se genera sola si la dejas en blanco), boolean (se dibuja como casilla), oauth (un botón de Conectar que corre el flujo de dispositivo de un proveedor para obtener un token), y cualquier pregunta puede marcarse con optional: true para permitir dejarla vacía. La lista completa está en Preguntas, en la referencia del formato de empaquetado. Al momento de instalar, el operador también elige en qué red se sirve el paquete.

Sistema de plantillas

Usa la sintaxis @variable@ para referirte a las respuestas de las preguntas y a las variables integradas (@LOCAL_EXTERNAL_HOST@, @LOCAL_INTERNAL_HOST@). Las plantillas funcionan en variables de entorno, asignaciones de puertos, cuotas y valores de las notas.

Probar en local

Usa el entorno de desarrollo para probar tu paquete. Pon tu repositorio en disco, agrégalo desde la interfaz o desde repositories.json, e instala tu paquete. El entorno de desarrollo te da todo Town OS para hacer pruebas.

Agregar un repositorio

Agrega tu repositorio de paquetes a Town OS desde la interfaz (Paquetes → Repositorios → Agregar repositorio) o editando repositories.json directamente:

[
  {"name": "default", "url": "https://github.com/town-os/default-packages"},
  {"name": "my-packages", "url": "https://github.com/myuser/my-packages"}
]

Entorno de desarrollo y suite de pruebas

El entorno de desarrollo de Town OS corre todo el sistema en local con contenedores de Podman. Es la manera más rápida de probar cambios, desarrollar paquetes y correr la suite de pruebas.

Requisitos previos

• Linux — necesario para btrfs y para los contenedores rootful de Podman
• Podman — entorno de contenedores (en modo rootful, con sudo)
• Go 1.25+ — para el servidor de la API
• Bun — para la construcción del frontend y su servidor de desarrollo
• btrfs-progs — para administrar el almacenamiento
• QEMU — qemu-system-x86_64 y qemu-img para los paquetes de máquina virtual
• libsystemd — cabeceras de desarrollo para la integración con systemd
• golangci-lint — para el análisis estático de Go
• Python 3 — para los scripts de construcción y de pruebas

Arrancar el entorno de desarrollo

git clone https://gitea.com/town-os/town-os.git
cd town-os
make dev

Eso levanta todo el entorno de desarrollo con recarga en caliente. Cuando esté listo, abre la URL que se imprime en la terminal para entrar al panel de Town OS.

Comandos del entorno de desarrollo

Correr las pruebas

Pruebas de integración

Las pruebas de integración corren dentro de un contenedor de Podman con privilegios que provee un sistema de archivos btrfs real, systemd y Podman dentro de Podman. Así las pruebas recorren los mismos caminos de código que una instalación en producción. El contenedor de pruebas es efímero — se crea nuevo en cada corrida y se limpia al terminar.