User Guide

Creating the USB Drive

The Town OS USB image is built from the install repository. The build process produces a bootable image with a squashfs root filesystem and a GPT partition layout.

Prerequisites

You'll need a Linux system with the following tools installed:

• make — the build is driven entirely by Makefiles
• squashfs-tools — for creating the compressed root filesystem
• parted and gdisk — for GPT partitioning
• A USB drive (8 GB or larger recommended)

Cloning and Building

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

Running make or make image builds the complete USB image. The process downloads the base system, installs Town OS components, compresses everything into a squashfs filesystem, and assembles the final disk image with a GPT partition table.

Partitioning and Squashfs

The resulting image uses a GPT layout with:

• An EFI system partition for booting
• A squashfs partition containing the compressed root filesystem

At boot time, Town OS mounts the squashfs as a read-only lower layer, with a tmpfs overlay on top. This means the OS runs entirely in RAM — the USB drive itself is only read at boot. All runtime changes happen in memory and are discarded on reboot, giving you a clean slate every time.

Writing the Image

Once the image is built, write it to your USB drive using dd:

# Find your USB device (e.g. /dev/sdb)
lsblk

# Write the image (replace /dev/sdX with your device)
sudo dd if=town-os.img of=/dev/sdX bs=4M status=progress conv=fsync

Double-check the target device — dd will overwrite whatever you point it at without confirmation.

Building VMs from USB Images

The install repository includes scripts for launching Town OS in virtual machines, which is useful for testing and development without a physical USB drive.

QEMU

make qemu

Launches a QEMU VM with KVM acceleration, 4 IDE drives for storage testing, and bridge networking. The VM boots from the USB image and behaves identically to a physical installation.

VirtualBox

make virtualbox

Creates a VirtualBox VM with bridged networking and converts the raw disk image to VDI format. Bridged mode lets the VM appear as a regular device on your network.

Auto-Detection

make run

Automatically detects your hypervisor — prefers QEMU if available, falls back to VirtualBox.

Environment Variables

Serial Console

# Attach to the VM serial console
make serial

# Or manually via socat
socat -,rawer,escape=0x1d unix-connect:/tmp/town-os-serial.sock

# Detach with Ctrl-]

Finding the VM

# Get the VM's IP address
make vm-ip

# Or connect via mDNS
ssh root@town-os.local

RAID Installation and ZFS

Town OS supports multiple storage backends for redundancy and performance. Configuration is driven by town-os.yaml, which can be placed on the USB drive or provided at boot.

Configuration

# town-os.yaml
storage_backend: btrfs       # btrfs, btrfs-mdadm, or zfs
btrfs_raid_mode: auto        # auto, single, raid1, raid5

btrfs Native RAID

With storage_backend: btrfs, Town OS uses btrfs's built-in RAID capabilities. In auto mode, the RAID level is selected based on disk count:

• 1 disk — single mode (no redundancy)
• 2 disks — RAID 1 (mirroring)
• 3+ disks — RAID 5 (striping with parity)

btrfs with mdadm

With storage_backend: btrfs-mdadm, Town OS creates an md-raid array first, then formats it with btrfs. This approach uses Linux's mature md-raid implementation underneath btrfs, which some administrators prefer for its proven reliability.

ZFS

With storage_backend: zfs, Town OS creates a ZFS pool with automatic topology selection:

• 2 disks — mirror (equivalent to RAID 1)
• 3+ disks — RAID-Z (equivalent to RAID 5)

ZFS datasets are created for each package's volumes, and ZFS block volumes (zvols) are available for packages that need raw block devices.

Disk Detection

Town OS automatically detects available storage devices. It identifies NVMe drives, SATA/SAS drives, and SD cards, while excluding the boot USB device and any removable media. The detection logic ensures that Town OS never touches the drive it booted from.

Overlay Filesystem

Regardless of storage backend, Town OS uses overlay mounts for /var and /etc persistence. The lower layer comes from the squashfs root, while the upper layer lives on the RAID/ZFS storage. This means system configuration and service data survive reboots while the base OS remains immutable.

Building a Package

Town OS packages are YAML files that describe how to run a containerized service. For the full specification, see the Packaging Format reference. This section covers the practical workflow.

Repository Structure

A package repository is a git repository with a packages/ directory. Each package gets a subdirectory containing versioned YAML definitions:

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

Writing a Package Definition

A minimal package needs only an image field. A typical package includes a description, networking, volumes, and user-facing questions:

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

Template System

Use @variable@ syntax to reference question answers and built-in variables (@LOCAL_EXTERNAL_HOST@, @LOCAL_INTERNAL_HOST@). Templates work in environment variables, port mappings, quotas, and note values.

Testing Locally

Use the dev environment to test your package. Place your repository on disk, add it through the UI or repositories.json, and install your package. The dev environment provides the full Town OS stack for testing.

Adding a Repository

Add your package repository to Town OS through the UI (Packages → Repositories → Add Repository) or by editing repositories.json directly:

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

Development Environment and Test Suite

The Town OS development environment runs the full stack locally using Podman containers. This is the fastest way to test changes, develop packages, and run the test suite.

Prerequisites

• Linux — required for btrfs and Podman rootless containers
• Podman — container runtime (rootless mode)
• Go 1.25+ — for the backend API server
• Bun — for the frontend build and dev server
• btrfs-progs — for storage management

Starting the Dev Environment

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

This starts the full development stack with hot-reloading. Once it's ready, open the URL printed in the terminal to access the Town OS dashboard.

Dev Environment Commands

Running Tests

Integration Tests

Integration tests run inside a privileged Podman container that provides a real btrfs filesystem, systemd, and Podman-in-Podman. This ensures tests exercise the same code paths as a production installation. The test container is ephemeral — it's created fresh for each test run and cleaned up afterward.