Formato de empaquetado

Definición de un paquete

Una definición completa de paquete en contenedor, con todos los campos disponibles:

image:
  url: nginx:1.26-alpine
description: Lightweight high-performance web server and reverse proxy
supplies: ["http"]
command: ["optional", "command", "override"]
environment:
  NGINX_HOST: "@hostname@"
network:
  external:
    "@port@": "80"
  internal:
    "5432": "5432"
  domains:
    - "@hostname@"
volumes:
  html:
    mountpoint: /usr/share/nginx/html
    quota: 2gb
    uid: 1000
    gid: 1000
  data:
    mountpoint: /data
    archive: seed-data.tar.gz
questions:
  hostname:
    query: "What hostname should nginx serve?"
    type: hostname
  port:
    query: "What external port should nginx listen on?"
    type: port
    default: "8080"
archives:
  - image: nginx:latest
    directory: /usr/share/nginx/html
    volume: html
git_sources:
  - url: "https://github.com/example/config.git"
    branch: main
    volume: data
templates:
  config:
    volume: data
    path: config.yaml
    content: |
      host: {{ .Responses.hostname }}
      port: {{ .Responses.port }}
      version: {{ .Package.Version }}
notes:
  URL:
    value: "http://@hostname@:@port@"
    type: url
  Support:
    value: "+1 (555) 123-4567"
    type: phone

El campo image también acepta una forma abreviada de cadena: image: nginx:1.26-alpine.

El campo image

El campo image identifica la imagen de contenedor que se va a ejecutar. Acepta dos formas:

# Forma de objeto
image:
  url: nginx:1.26-alpine
  type: oci                # opcional, por omisión "oci"

# Forma abreviada de cadena
image: nginx:1.26-alpine

Los nombres cortos de imagen se normalizan solos durante la compilación:

El único valor válido de type es oci (el predeterminado). Las URL de imagen solo pueden contener caracteres alfanuméricos, @, ., _, :, / y - — los metacaracteres del shell se rechazan.

Configuración de red

Los valores de puerto deben ser enteros entre 1 y 65535 después de sustituir las plantillas. Omite external, internal o domains por completo si no los usas — no pongas mapas ni listas vacías.

La clave de una entrada de puerto es o bien una cadena numérica de puerto ("2222": "22") o bien un nombre semántico que cumpla ^[a-zA-Z][a-zA-Z0-9_]*$ (http: "3000"). Ponerle nombre a un puerto permite que los paquetes padre lo referencien por su papel (@dep_KEY_port_http@) en lugar de por número, y — para el nombre especial http — inscribe ese puerto en la entrada HTTP compartida que se describe abajo.

Entrada HTTP (el puerto llamado http)

Town OS ejecuta una sola entrada compartida en el puerto :443 que termina el TLS de todos los paquetes y hace de proxy inverso hacia el puerto HTTP en claro del contenedor. Un paquete se suma a esa entrada llamando http a un puerto internal:

network:
  internal:
    http: "3000"      # puerto HTTP en claro del contenedor

Cuando haces esto:

• El servicio queda accesible en https://<PACKAGE_DNS>/ — sin puerto en la URL. No hay puerto del anfitrión que elegir; tampoco asignes el puerto HTTP bajo external.
• La entrada presenta un certificado hoja de confianza local (emitido por la CA integrada de Rolodex) para <PACKAGE_DNS> (por ejemplo gitea.default.home), y Rolodex publica registros DANE TLSA en _443 para que los clientes que entienden DANE puedan fijar el certificado.
• Como la entrada es dueña del :443, cualquier URL que genere la aplicación tiene que ser HTTPS sin puerto. Configura la URL pública de la aplicación en consecuencia (por ejemplo, el GITEA__server__ROOT_URL: "https://@PACKAGE_DNS@/" de gitea) y deja que la aplicación siga escuchando en HTTP en claro dentro del contenedor.

Los protocolos que no son HTTP (SSH, bases de datos, etc.) no deben usar el nombre http — no son HTTP y la entrada no puede terminarles el TLS. Redirígelos tal cual con una asignación numérica:

network:
  internal:
    http: "3000"          # detrás de la entrada :443, con TLS terminado
    "@sshport@": "22"     # redirección TCP pura, nunca envuelta en TLS

Nombres de cara a internet (domains)

De forma predeterminada, la entrada solo sirve el nombre <PACKAGE_DNS> de confianza local. Para exponer además un servicio a internet con un certificado de confianza pública, lista los FQDN reales bajo network.domains y apunta el DNS público de ese nombre a este anfitrión. La entrada obtiene un certificado ACME (Let’s Encrypt) para cada dominio listado:

network:
  internal:
    http: "3000"
  domains:
    - git.example.com

Ficheros comprimidos

El campo archives extrae ficheros desde imágenes de contenedor hacia los volúmenes durante la instalación:

archives:
  - image: nginx:latest
    directory: /usr/share/nginx/html
    volume: html

Si el volumen de destino está vacío durante la instalación o la reconciliación, Podman descarga la imagen, crea un contenedor temporal y copia el directorio indicado dentro del volumen.

Preguntas

Las preguntas definen los mensajes interactivos que aparecen al instalar un paquete. Las respuestas del usuario sustituyen los marcadores de plantilla @name@ por toda la definición.

questions:
  port:
    query: "What external port should nginx listen on?"
    type: port
    default: "8080"

Tipos de pregunta

Preguntas booleanas

Una pregunta boolean se muestra como casilla en vez de campo de texto, y su respuesta se sustituye como la cadena literal true o false. Como una casilla sin marcar sigue siendo una respuesta de verdad, el usuario puede apagar una pregunta con default: "true" — el false explícito prevalece sobre el predeterminado.

environment:
  REGISTRATION_OPEN: "@open@"
  METRICS_ENABLED: "@metrics@"
questions:
  open:
    query: "Allow open registration?"
    type: boolean          # sin responder -> "false"
  metrics:
    query: "Enable metrics?"
    type: boolean
    default: "true"        # sin responder -> "true"

El valor normalizado es también lo que ven las plantillas de fichero, así que {{ .Responses.metrics }} se genera como true o false y se puede evaluar con {{ if eq .Responses.metrics "true" }}.

Preguntas opcionales

Toda pregunta debe responderse con un valor no vacío, salvo que declare optional: true. Sin eso, un ajuste del que la aplicación realmente puede prescindir — un relay SMTP, una clave de API — no tiene forma honesta de expresarse: el autor tiene que inventarse un valor de relleno y confiar en que el operador lo cambie.

environment:
  SMTP_HOST: "@smtp_host@"
  SMTP_PORT: "@smtp_port@"
questions:
  smtp_host:
    query: "SMTP server hostname"
    optional: true
  smtp_port:
    query: "SMTP server port"
    type: port
    optional: true
    default: "587"

Si se deja en blanco, una pregunta opcional sustituye la cadena vacía en sus marcadores @marker@, de modo que la aplicación ve la variable vacía en vez de puesta en algo que nadie eligió. Nunca se genera sola: un secret opcional en blanco se queda en blanco, en lugar de convertirse en una cadena aleatoria con la que la aplicación intentaría autenticarse obedientemente.

optional se combina con type — un puerto opcional que sí se respondió se sigue validando como puerto, mientras que uno en blanco se compila hasta desaparecer. No tiene sentido en un boolean, que es una casilla y siempre acaba en uno de sus dos valores.

Preguntas OAuth

Algunas aplicaciones se configuran con una credencial que solo su proveedor puede emitir — un token de cuenta de Plex, un token personal de GitHub — y lo normal para conseguirla es ejecutar un script en una terminal y pegar lo que imprime. Una pregunta oauth ejecuta ese flujo desde el diálogo de instalación: el operador pulsa Conectar, aprueba en una pestaña del navegador, y el token que vuelve se convierte en la respuesta.

No hay un registro de proveedores. La pregunta trae un bloque oauth que nombra las URL del propio proveedor, así que cualquier proveedor con un flujo de tipo dispositivo funciona sin cambiarle nada a Town OS.

environment:
  PLEX_TOKEN: "@plextoken@"
questions:
  plextoken:
    query: "Plex account"
    type: oauth
    oauth:
      start:
        method: POST
        url: "https://plex.tv/api/v2/pins?strong=true"
        headers:
          X-Plex-Client-Identifier: "{{client_id}}"
      extract:
        id: id
        code: code
      approve: "https://app.plex.tv/auth#?clientID={{client_id}}&code={{code}}"
      poll:
        url: "https://plex.tv/api/v2/pins/{{id}}"
        headers:
          X-Plex-Client-Identifier: "{{client_id}}"
      token: authToken
      interval: 2s
      timeout: 10m

Los marcadores {{...}} en las URL, las cabeceras y los valores de formulario se resuelven con lo que haya nombrado extract, más {{client_id}} — un identificador aleatorio que Town OS genera por cada flujo y envía en cada paso, que es a lo que Plex ata su pin.

El token es una credencial, así que se trata como tal: enmascarado en el panel de información del paquete, copiable pero nunca impreso. Se cachea igual que cualquier otra respuesta, así que reinstalar o actualizar lo reutiliza en vez de mandar al operador de vuelta con el proveedor.

Como quien llama a esas URL es el controlador del sistema — no el navegador — tienen que ser https y no pueden resolverse a una dirección de bucle local, privada, de enlace local ni de CGNAT. La comprobación se hace cuando la conexión se establece de verdad, y otra vez en cada redirección, así que un paquete no puede usar un flujo para que el controlador meta la mano en la propia red del anfitrión.

Notas

Las notas ofrecen datos de clave y valor que se muestran después de instalar.

notes:
  URL:
    value: "http://localhost:@port@"
    type: url
  Info:
    value: "Default admin credentials are admin/admin"

Dependencias

Los paquetes pueden declarar dependencias de otros paquetes. Las dependencias comparten la red de podman del paquete padre, lo que permite que los contenedores del mismo árbol de dependencias se comuniquen directamente por nombre de contenedor gracias al DNS integrado de podman.

dependencies:
  db:
    package: postgres
    responses:
      password: "@dbpass@"
      user: "mattermost"
      database: "mattermost"
      port: "5432"

Los paquetes padre reciben variables de entorno para cada dependencia en tiempo de ejecución: TOWNOS_DEP_{KEY}_HOST (el nombre del contenedor) y TOWNOS_DEP_{KEY}_PORT_{port} (el número de puerto del lado del contenedor). Los padres también pueden usar las variables de plantilla @dep_KEY_host@ y @dep_KEY_port_N@ en los valores de su entorno (mira el sistema de plantillas).

Ejemplo: un paquete de Mattermost con una dependencia db de PostgreSQL puede referirse al host de la base de datos en su URL de origen de datos:

environment:
  MM_SQLSETTINGS_DATASOURCE: "postgres://mattermost:@dbpass@@@dep_db_host@:@dep_db_port_5432@/mattermost?sslmode=disable"

Entorno de máquina virtual

Los paquetes pueden ejecutar máquinas virtuales en lugar de contenedores, especificando un campo vm en vez de image:

vm:
  image: "https://example.com/my-vm.qcow2"
  memory: 2gb
  cpus: 2
description: A virtual machine package

El campo vm es mutuamente excluyente con image y proton. Las imágenes de máquina virtual no se normalizan como las de contenedor.

Compilación

La compilación transforma la definición de un paquete y las respuestas del usuario en una configuración completamente resuelta y lista para ejecutarse. La secuencia de compilación hace estos pasos:

• Valida todas las respuestas contra los tipos declarados
• Aplica la validación propia de cada tipo (rangos de puertos, patrones de nombre de host, análisis de bytes, etc.)
• Sustituye todos los marcadores de plantilla @variable@ por los valores resueltos
• Normaliza las URL de las imágenes de contenedor a referencias completamente cualificadas
• Produce un paquete resuelto y listo para instalarse

En los paquetes de máquina virtual, las cadenas de memoria (por ejemplo 2gb) se convierten a cantidad de bytes y se aplican los valores predeterminados de CPU. Los errores de validación se juntan de todos los campos y se devuelven de una vez, para que el usuario pueda arreglarlo todo en una sola pasada en lugar de irse topando con los errores uno por uno.

Flujo de instalación

Instalar un paquete recorre una secuencia de pasos bien definida. El proceso se encarga de todo, desde preparar los ficheros hasta arrancar el servicio:

• Crear un enlace duro desde el fichero del paquete en el repositorio hacia el directorio de instalados
• Persistir las respuestas (la de esa versión y la copia last)
• Crear los volúmenes con sus cuotas y, si procede, con propietario UID/GID
• Rellenar los volúmenes desde ficheros comprimidos y orígenes git (solo en el entorno de contenedor)
• Aplicar las plantillas (generar los ficheros dentro de los volúmenes)
• Generar la unidad de systemd (basada en Podman para contenedores, en QEMU para máquinas virtuales)
• Crear el fichero de estado de red
• Arrancar el servicio
• Borrar las respuestas de last si todo ha ido bien

Hay dos indicadores opcionales que controlan el comportamiento de los volúmenes:

• reuse_volumes — reutiliza los volúmenes de una versión anterior desinstalada del mismo paquete
• import_from_version — importa los volúmenes de una versión anterior concreta

Vista previa de la instalación

Antes de comprometerte con una instalación, puedes ver qué se crearía. El endpoint de vista previa (POST /packages/install-preview) devuelve un resumen de la instalación planificada sin hacer ningún cambio:

• Los volúmenes que se crearían
• Los puertos que se asignarían
• Información de la actualización (si vienes de una versión anterior)
• El tipo de entorno (contenedor o máquina virtual)
• Si el paquete tiene preguntas que responder
• Los detalles de la máquina virtual (imagen, memoria, CPU) en los paquetes de ese tipo

Importar repositorios

Una vez que hayas creado un repositorio de paquetes, añádelo a tu instancia de Town OS desde la interfaz web o configurando el sistema de ficheros directamente.

Desde la interfaz

Entra en el panel de Town OS, ve a Paquetes, elige la pestaña Repositorios y pulsa Añadir repositorio. Pon un nombre, la URL de git y, si hace falta, las credenciales. Pulsa Actualizar para traer los metadatos de los paquetes de inmediato.

Desde el sistema de ficheros

Edita repositories.json en el directorio btrfs de datos de paquetes. El fichero es un array JSON de objetos:

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

El orden importa — las entradas posteriores prevalecen sobre las anteriores cuando los nombres de paquete chocan. Para repositorios privados, mete las credenciales en la URL. Reinicia el servicio o pulsa Actualizar en la interfaz para que los cambios surtan efecto.

Guía de estilo

• Omite los mapas vacíos (environment: , internal: , volumes: ) — déjalos fuera por completo.
• Omite type en las preguntas que aceptan texto libre — no escribas type: sin valor.
• Incluye description con un resumen breve de qué es el paquete.
• Incluye supplies con las etiquetas de capacidad que correspondan cuando el paquete ofrezca un servicio conocido.
• Incluye notes con las URL de conexión y cualquier información importante posterior a la instalación.
• Usa plantillas @variable@ para que el usuario personalice puertos, nombres de host y credenciales durante la instalación.
• Usa templates para los ficheros de configuración que necesiten lógica de plantillas de Go — solo se escriben una vez y conservan las ediciones del usuario.