Guía del usuario

Compilar la imagen USB desde el código

La imagen USB de Town OS se compila desde el repositorio install. El proceso produce una imagen arrancable con un sistema de ficheros 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 compilación usa herramientas de Arch Linux (pacstrap, mkinitcpio, arch-chroot), pero no hace falta que ejecutes Arch — en cualquier otra distribución, make image lanza la compilació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 compilación y las herramientas de máquinas virtuales — make, podman, arch-install-scripts, squashfs-tools, parted, e2fsprogs, dosfstools, qemu y libvirt.

Clonar y compilar

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

Ejecutar make o make image compila la imagen USB completa. El proceso descarga el sistema base, instala los componentes de Town OS, comprime todo en un sistema de ficheros squashfs y monta 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 ficheros 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 se ejecuta 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 compila la imagen si está desactualizada y la graba en un dispositivo USB. Si prefieres hacerlo a mano, ten en cuenta que la compilación produce un fichero 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 fichero 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

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

Configurar el DNS en tu router

Town OS incluye rolodex, un servidor DNS que gestiona 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 en el 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
• Ejecuta 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 fiable, 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 añadié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 en 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 habituales

Desactiva el DNS del navegador

La mayoría de los navegadores traen su propio resolutor 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 envían las consultas directamente a un proveedor público como Cloudflare o NextDNS, así que Town OS nunca ve la consulta y los nombres de tus paquetes vuelven 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 — Ajustes → 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 resolutor del sistema. Comprueba que no haya un perfil de DNS instalado en Ajustes del Sistema → General → VPN, DNS y gestión de dispositivos.

Lo mismo se 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 (mira Elegir un modo de resolución más abajo).

Comprueba que funcione

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

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

# O consulta directamente 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 resolutor 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 entregue a un resolutor 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 envía las consultas que no coinciden a resolutores 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 el ordenador llega a internet. El DNS cifrado en la otra dirección — el que usan tus propios dispositivos para llegar al ordenador — 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 del propio ordenador, con el mismo nombre y las mismas direcciones que usa el resto del sistema. Si ya has instalado la CA raíz en el dispositivo (véase 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 resolutor, puede descargar la fijación, y así puede comprobar lo que se le entrega 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 ordenador 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 el ordenador simplemente está encendido — 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 gestiona 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 a 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 cachea por adelantado una lista de bloqueo. No se comprueba nada hasta que activas una categoría y añades 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 lanza 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 agota el tiempo se trata como no listado, así que una lista de bloqueo inalcanzable nunca deja tu red sin conexión.
• Las listas de bloqueo ganan al mundo exterior, nunca a tus propios registros — la comprobació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 liste también ese nombre. Tumbar un dominio entero por un solo host listado es una decisión tuya, no de la lista.
• Los resultados se cachean un rato — un listado durante el TTL del proveedor, un resultado limpio durante cinco minutos.

Proveedores DNSBL

Estos son los que puedes añadir con un clic desde el panel. Todos siguen operando, son gratuitos y responden a un resolutor 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. Comprobar 192.168.1.100 contra zen.spamhaus.org lanza 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 cachean 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 a la navegación. Actívalas si tienes 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 añadirlas 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 comprueba 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 comprobació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 — eximir vendor.example también exime 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 cachea nada a tus espaldas. Si quieres que un dominio de anuncios o rastreo concreto desaparezca, añádelo 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 funcionando, 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 gestiona 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

Pulsa 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).
• Ejecuta un resolutor 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 funcionando 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 pulsa Añadir par. Town OS te devuelve una configuración de WireGuard lista para importar — pégala en la app de WireGuard de tu móvil o tu portátil.

Copia la configuración de inmediato. Contiene una clave 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á levantado. Deja apagado el interruptor Ejecuta rolodex DNS para los dispositivos normales; enciéndelo solo para un par que a su vez ejecute un servidor DNS rolodex al que quieras reenviar.

Cuentas solo de WireGuard

Para dejar que alguien dé de alta sus propios dispositivos sin darle vía libre en el 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 añade 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 clave, 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 en marcha, el servicio aparece en tu Panel como un enlace en el que puedes pulsar con esa dirección, listo para abrirse desde cualquier dispositivo de la red.

Crear 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 compilaste tú o directamente desde una memoria USB física que ya grabaste. make help lista todos los objetivos y variables.

QEMU

make qemu-fg

Compila la imagen si está desactualizada y luego levanta una máquina virtual de QEMU en primer plano, con la consola serie 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 directamente en tu terminal, y Ctrl-C detiene la máquina. Usa make qemu si prefieres que se ejecute en segundo plano (conéctate después con make serial), y make rebuild-qemu para detener, limpiar, recompilar y relanzar de una vez.

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 ejecutes a la vez.

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 móvil 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 compilada — 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 compila 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 serie

# Conéctate a la consola serie 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 ficheros 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.

Alojar sitios estáticos

Más allá de los paquetes en contenedores, Town OS trae alojamiento de sitios estáticos integrado, siempre activo y gestionado 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 fichero — 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 aprovisionan de forma asíncrona — la tabla muestra una insignia de Aprovisionando… que acaba en activa o en error. Usa Recompilar para traer el contenido más reciente en las páginas de git y de contenedor; en una página de fichero, 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 ficheros YAML que describen cómo ejecutar un servicio en contenedor. Para la especificación completa, mira 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 ejecuta 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. Durante la instalación, 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, añádelo desde la interfaz o desde repositories.json, e instala tu paquete. El entorno de desarrollo te da todo Town OS para hacer pruebas.

Añadir un repositorio

Añade tu repositorio de paquetes a Town OS desde la interfaz (Paquetes → Repositorios → Añadir 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 batería de pruebas

El entorno de desarrollo de Town OS ejecuta todo el sistema en local con contenedores de Podman. Es la manera más rápida de probar cambios, desarrollar paquetes y lanzar la batería 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 compilación del frontend y su servidor de desarrollo
• btrfs-progs — para gestionar 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 compilació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 en el panel de Town OS.

Comandos del entorno de desarrollo

Lanzar las pruebas

Pruebas de integración

Las pruebas de integración se ejecutan dentro de un contenedor de Podman con privilegios que provee un sistema de ficheros 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 ejecución y se limpia al terminar.