Packaging Format

Package Definition

A complete container package definition with all available fields:

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

The image field also accepts a shorthand string form: image: nginx:1.26-alpine.

Image Field

The image field identifies the container image to run. It accepts two forms:

# Object form
image:
  url: nginx:1.26-alpine
  type: oci                # optional, defaults to "oci"

# Shorthand string form
image: nginx:1.26-alpine

Short image names are automatically normalized during compilation:

The only valid type value is oci (the default). Image URLs must contain only alphanumeric characters, @, ., _, :, /, and - — shell metacharacters are rejected.

Network Configuration

Port values must be integers between 1 and 65535 after template substitution. Omit external, internal, or domains entirely if unused — do not use empty maps or lists.

A port entry’s key is either a numeric port string ("2222": "22") or a semantic name matching ^[a-zA-Z][a-zA-Z0-9_]*$ (http: "3000"). Naming a port lets parents reference it by role (@dep_KEY_port_http@) instead of by number, and — for the special name http — opts the port into the shared HTTP ingress described below.

HTTP ingress (the http named port)

Town OS runs a single shared ingress on port :443 that terminates TLS for every package and reverse-proxies to the package’s plain-HTTP container port. A package joins the ingress by naming an internal port http:

network:
  internal:
    http: "3000"      # container's plain-HTTP port

When you do this:

• The service is reachable at https://<PACKAGE_DNS>/ — no port in the URL. There is no host port to choose; do not also map the HTTP port under external.
• The ingress serves a locally-trusted leaf certificate (issued by the built-in Rolodex CA) for <PACKAGE_DNS> (e.g. gitea.default.home), and Rolodex publishes DANE TLSA records on _443 so DANE-aware clients can pin the certificate.
• Because the ingress owns :443, any URL the app generates must be port-less HTTPS. Set the app’s public URL accordingly (e.g. gitea’s GITEA__server__ROOT_URL: "https://@PACKAGE_DNS@/"), and leave the app listening on plain HTTP inside the container.

Non-HTTP protocols (SSH, databases, etc.) must not use the http name — they are not HTTP and cannot be TLS-terminated by the ingress. Forward them untouched with a numeric mapping instead:

network:
  internal:
    http: "3000"          # fronted by the :443 ingress, TLS-terminated
    "@sshport@": "22"     # raw TCP forward, never wrapped in TLS

Internet-facing names (domains)

By default the ingress only serves the locally-trusted <PACKAGE_DNS> name. To additionally expose a service to the public internet with a publicly-trusted certificate, list the real FQDN(s) under network.domains and point that name’s public DNS at this host. The ingress obtains an ACME (Let’s Encrypt) certificate for each listed domain:

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

Archives

The archives field extracts files from container images into volumes at install time:

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

If the target volume is empty during install or reconcile, Podman pulls the image, creates a temporary container, and copies the specified directory into the volume.

Questions

Questions define interactive prompts shown during package installation. User responses replace @name@ template markers throughout the definition.

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

Question Types

Boolean Questions

A boolean question is shown as a checkbox rather than a text field, and its answer is substituted as the literal string true or false. Because an unchecked box is still a real answer, a question with default: "true" can be turned off by the user — the explicit false wins over the default.

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

The normalized value is what file templates see too, so {{ .Responses.metrics }} renders as true or false and can be tested with {{ if eq .Responses.metrics "true" }}.

Optional Questions

Every question must be answered with a non-empty value unless it declares optional: true. Without it, a setting the application can genuinely do without — an SMTP relay, an API key — has no honest expression: the author has to invent a placeholder default and hope the operator overwrites it.

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"

Left blank, an optional question substitutes the empty string at its @marker@ sites, so the application sees the variable empty rather than set to something nobody chose. It is never auto-generated: a blank optional secret stays blank instead of becoming a random string the application would dutifully try to authenticate with.

optional composes with type — an answered optional port is still validated as a port, while a blank one compiles away to nothing. It is meaningless on a boolean, which is a checkbox and always resolves to one of its two values.

OAuth Questions

Some applications are configured with a credential only their vendor can mint — a Plex account token, a GitHub personal token — and the usual way to get one is to run a script in a terminal and paste what it prints. An oauth question runs that flow from the install dialog instead: the operator clicks Connect, approves in a browser tab, and the token that comes back becomes the answer.

There is no provider registry. The question carries an oauth block naming the provider’s own URLs, so any vendor with a device-style flow works without a change to 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

{{...}} placeholders in URLs, headers, and form values resolve against whatever extract named, plus {{client_id}} — a random identifier Town OS generates per flow and sends on every step, which is what Plex ties its pin to.

The token is a credential, so it is treated as one: masked in the package info panel, copyable but never printed. It is cached like any other response, so reinstalling or upgrading reuses it rather than sending the operator back to the provider.

Because it is the system controller — not the browser — that calls these URLs, they must be https and must not resolve to a loopback, private, link-local, or CGNAT address. The check runs when the connection is actually made, and again on every redirect, so a package cannot use a flow to make the controller reach into the host’s own network.

Notes

Notes provide key-value metadata displayed after installation.

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

Dependencies

Packages can declare dependencies on other packages. Dependencies share the parent's podman network, allowing containers in the same dependency tree to communicate directly by container name via podman's built-in DNS.

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

Parent packages receive environment variables for each dependency at runtime: TOWNOS_DEP_{KEY}_HOST (the container name) and TOWNOS_DEP_{KEY}_PORT_{port} (container-side port number). Parents can also use @dep_KEY_host@ and @dep_KEY_port_N@ template variables in their environment values (see Template System).

Example: A Mattermost package with a db dependency on PostgreSQL can reference the database host in its datasource URL:

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

VM Runtime

Packages can run virtual machines instead of containers by specifying a vm field instead of image:

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

The vm field is mutually exclusive with image and proton. VM images are not normalized like container images.

Compilation

Compilation transforms a package definition and user responses into a fully resolved, runnable configuration. The compile pipeline performs these steps:

• Validates all question responses against their declared types
• Applies type-specific validation (port ranges, hostname patterns, byte parsing, etc.)
• Substitutes all @variable@ template markers with resolved values
• Normalizes container image URLs to fully qualified references
• Produces a resolved package ready for installation

For VM packages, memory strings (e.g. 2gb) are parsed to byte counts and CPU defaults are applied. Validation errors are collected across all fields and returned together, so users can fix everything in one pass rather than hitting errors one at a time.

Installation Workflow

Installing a package runs through a defined sequence of steps. The process handles everything from file setup through service startup:

• Hard link creation from the repository package file to the installed directory
• Response persistence (version-specific and last copy)
• Volume creation with quotas and optional UID/GID ownership
• Volume seeding from archives and git sources (container runtime only)
• Template application (files rendered into volumes)
• Systemd unit generation (Podman-based for containers, QEMU-based for VMs)
• Network state file creation
• Service start
• Last response clearing on success

Two optional flags control volume behavior:

• reuse_volumes — reuse volumes from a previous uninstalled version of the same package
• import_from_version — import volumes from a specific prior version

Install Preview

Before committing to an install, you can preview what would be created. The install preview endpoint (POST /packages/install-preview) returns a summary of the planned installation without making any changes:

• Volumes that would be created
• Ports that would be mapped
• Upgrade information (if upgrading from a previous version)
• Runtime type (container or VM)
• Whether the package has questions to answer
• VM configuration details (image, memory, CPUs) for VM packages

Importing Repositories

Once you've created a package repository, add it to your Town OS instance using either the web UI or direct filesystem configuration.

Via the UI

Log in to the Town OS dashboard, navigate to Packages, select the Repositories tab, and click Add Repository. Provide a name, the git URL, and optional credentials. Click Refresh to pull package metadata immediately.

Via the Filesystem

Edit repositories.json in the btrfs package data directory. The file is a JSON array of objects:

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

Order matters — later entries override earlier ones when package names collide. For private repositories, embed credentials in the URL. Restart the service or hit Refresh in the UI for changes to take effect.

Style Guidelines

• Omit empty maps (environment: , internal: , volumes: ) — leave them out entirely.
• Omit type on questions that accept free-form text — do not write type: with no value.
• Include description with a short summary of what the package is.
• Include supplies with relevant capability tags when the package provides a well-known service.
• Include notes with connection URLs and any important post-install information.
• Use @variable@ templates to let users customize ports, hostnames, and credentials at install time.
• Use templates for config files that need Go template logic — they are only written once and preserve user edits.