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.

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

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.