ユーザーガイド

ソースから USB イメージをビルドする

Town OS の USB イメージは install リポジトリからビルドされます。ビルドの過程で、squashfs のルートファイルシステムと GPT のパーティション構成を持つ起動可能イメージが生成されます。

事前に必要なもの

Linux ホストと USB メモリ（4 GB 以上）が必要です。ビルドには Arch Linux のツール （pacstrap、mkinitcpio、arch-chroot）を使いますが、 Arch を動かしている必要はありません。ほかのディストリビューションでは、 make image が同じアーキテクチャの Arch コンテナー内で自動的にビルドを実行します。 ホスト側の依存関係は、お使いのディストリビューション向けの同梱ターゲットで インストールしてください。

• make deps — Arch（および派生）または Fedora/RHEL
• make deps-debian — Debian または Ubuntu

これらは、ビルドと VM ツールに必要なものをすべて導入します。make、 podman、arch-install-scripts、squashfs-tools、 parted、e2fsprogs、dosfstools、 qemu、libvirt です。

クローンとビルド

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

make または make image を実行すると、完全な USB イメージが ビルドされます。この処理では、ベースシステムをダウンロードし、Town OS の コンポーネントをインストールし、すべてを squashfs ファイルシステムへ圧縮して、 GPT のパーティションテーブルを持つ最終的なディスクイメージを組み立てます。

パーティションと squashfs

できあがるイメージは、次の構成の GPT レイアウトになります。

• レガシー BIOS 起動用の BIOS ブートパーティション（1 MiB）
• UEFI 起動用の EFI システムパーティション（64 MiB、FAT32）
• squashfs のルートファイルシステムと GRUB を含むデータパーティション（ext4）

起動時、Town OS は squashfs を読み取り専用の下位レイヤーとしてマウントし、その上に tmpfs のオーバーレイを重ねます。つまり OS はすべて RAM 上で動作し、USB メモリ自体は 起動時に読み込まれるだけです。実行中の変更はすべてメモリ上で行われ、再起動時に 破棄されるため、毎回まっさらな状態から始まります。

イメージの書き込み

いちばん簡単なのは make flash です。イメージが古ければビルドし直し、 USB デバイスへ書き込みます。手作業で行う場合、ビルドは日付とアーキテクチャが 付いたファイル名（例: town-os-2026-07-25-x86_64.img）を生成するので、dd で書き込みます。

# USB デバイスを探す（例: /dev/sdb）
lsblk

# イメージを書き込む（ファイル名と /dev/sdX は自分のデバイスに置き換える）
sudo dd if=town-os-YYYY-MM-DD-x86_64.img of=/dev/sdX bs=4M status=progress conv=fsync

対象のデバイスは必ず確認してください。dd は指定された先を、確認なしに 上書きします。

ルーターで DNS を設定する

Town OS には rolodex が含まれています。パッケージ用の権威ゾーンを管理し、上位への問い合わせを転送する DNS サーバーです。これをネットワークの DNS サーバーとして使うには、Town OS マシンの IP アドレスをネットワークの DNS サーバーとして配るよう、ルーターに指示する必要があります。 こうすれば、ネットワーク上のすべての端末が自動的に rolodex を使うようになり、 端末ごとの設定は不要です。

Town OS の IP アドレスを調べる

Town OS マシンのローカル IP アドレスが必要です。次の方法で調べられます。

• 初回起動のセットアップ後に http://town-os.local でダッシュボードにログインし、表示されている内部 IP を確認する。これが DNS サーバーとして使うアドレスです
• VM を使っている場合は make vm-ip を実行する
• ルーターの DHCP クライアント一覧から "town-os" という名前の端末を探す

DNS を安定して動かすには、Town OS マシンに静的 IP アドレスか、ルーター上の DHCP 予約を割り当てておく必要があります。IP が変わると、ネットワーク全体の DNS が使えなくなります。

静的 IP または DHCP 予約を割り当てる

たいていのルーターでは、MAC アドレスをもとに特定の端末へ IP アドレスを予約できます。 通常は LAN 設定、DHCP、 アドレス予約といった項目にあります。クライアント一覧から Town OS の マシンを見つけ、現在の IP を予約してください。

ルーターが DHCP 予約に対応していない場合は、town-os.yaml に追記することで Town OS マシン側に静的 IP を設定できます。

ルーターの DNS サーバーを変更する

正確な手順はルーターのメーカーによって異なりますが、大まかな流れは同じです。

1. ルーターの管理画面にログインします（通常は 192.168.1.1 か 192.168.0.1）
2. DHCP 設定、LAN 設定、DNS 設定のいずれかの項目を探します
3. プライマリ DNS サーバーを Town OS マシンの IP アドレスに変更します
4. 必要なら予備としてセカンダリ DNS サーバーを設定します（例: 1.1.1.1 や 8.8.8.8）。Town OS に到達できないときに使われます
5. 設定を保存して適用します

保存後、ネットワーク上の端末は次に DHCP のリース更新を行ったときに新しい DNS サーバーを 受け取ります。ネットワークに接続し直すか、端末を再起動すれば、すぐに反映できます。

よくあるルーターの管理画面

ブラウザー内蔵の DNS を無効にする

ほとんどのブラウザーは独自の DNS リゾルバーを持っており、ルーターを完全に迂回します。 Firefox の DNS over HTTPS（DoH）や、Chrome・Edge の同等の「セキュア DNS」機能は、 問い合わせを Cloudflare や NextDNS といった公開プロバイダーへ直接送ります。その結果、 Town OS には問い合わせが届かず、ネットワークのほかの部分では問題なく解決できるのに、 パッケージ名だけ「サーバーが見つかりません」となります。サービスに名前でアクセスしたい 端末では、次の設定をすべてオフにしてください。

• Firefox — 設定 → プライバシーとセキュリティ → DNS over HTTPS で オフを選びます。（既定の保護でも DoH が黙って有効になることがあるため、既定のままにせずオフを選んでください。）
• Chrome — 設定 → プライバシーとセキュリティ → セキュリティでセキュア DNS を使用するをオフにします。
• Edge — 設定 → プライバシー、検索、サービス → セキュリティでセキュア DNS を使用してネットワーク アドレスの参照方法を指定するをオフにします。
• Brave、Vivaldi、Opera — Chrome と同じ設定で、プライバシーとセキュリティ → セキュリティにあります。
• Safari — 内蔵の DoH はなく、システムのリゾルバーを使います。システム設定 → 一般 → VPN とデバイス管理に DNS プロファイルが入っていないか確認してください。

システム全体で暗号化 DNS を設定している場合も同様です。Android の プライベート DNS、iOS/macOS の DNS プロファイル、ローカルの systemd-resolved/dnscrypt の設定などは、いずれもルーターが 配る DNS サーバーを上書きします。上位への問い合わせを暗号化したい場合は、Town OS に 任せてください。rolodex はローカルの名前に答えつつ、上位に対して DoH/DoT を使えます （下記の解決モードを選ぶを参照）。

動作を確認する

端末が新しい DNS 設定を受け取ったら、rolodex が DNS の問い合わせを処理していることを 確認します。

# どの DNS サーバーを使っているか確認する
nslookup example.com

# または Town OS に直接問い合わせる
dig @<town-os-ip> example.com

# パッケージのドメインを問い合わせる（パッケージをインストール済みの場合）。
# 名前は <name>.<repo>.<tld> の形式で、.home が既定のネットワークの TLD
dig @<town-os-ip> gitea.default.home

example.com が正しく解決されれば、rolodex は動作しており、 ネットワークの DNS を処理できています。

解決モードを選ぶ

自分のネットワークに属さない名前は解決モードに従って解決されます。 モードはダッシュボードの 設定 → DNS 解決で指定します。 3 つのモードがあります。

• 自動（推奨） — 既定のモードです。まずルートサーバーから反復的に解決しようとし、うまくいかない場合は DoH/DoT、ローカルのフォワーダー、最後に公開リゾルバーへと順に切り替え、最後に成功した段階を維持します。ネットワークが許す限り再帰解決のプライバシーを保ちつつ、外向きの DNS がフィルタリングされる環境でも無理なく機能を落として動きます。
• 再帰のみ — すべてをルートサーバーから反復的に解決し、代替手段は使いません。第三者のリゾルバーに問い合わせが渡らないことを保証できますが、外向きのポート 53 を遮断・乗っ取るネットワーク（ホテル、キャプティブポータル、一部の ISP）では外部の名前がすべて解決できなくなります。
• 転送 — 一致しない問い合わせを常に上位のリゾルバー（既定では Google Public DNS）へ送ります。従来からある転送の動作です。

この設定は、この機器がインターネットへ到達する方法についてのものである点にご注意ください。 逆方向の暗号化 DNS、つまりお使いの端末がこの機器へ到達するために使うものについては、次に説明します。

お使いの端末から暗号化 DNS を使う

Town OS は自分自身のためだけでなく、お使いの端末に対しても暗号化 DNS を提供します。 利用できるエンドポイントは三つあり、いずれもポート 53 の平文 DNS とまったく同じ名前に応答します。

• DNS over HTTPS（DoH） — https://dns.<tld>/dns-query。これは ingress を経由して標準の HTTPS ポートを使うので、制限の厳しいネットワークでも最も通りやすいものです。
• DNS over TLS（DoT） — dns.<tld> のポート 853。
• DNS over QUIC（DoQ） — dns.<tld> のポート 853、UDP 上。

三つとも、この機器自身の認証局が発行した証明書を提示します。名前もアドレスも、 システムのほかの部分が使っているものと同じです。端末にルート CA を既にインストールしてあるなら （認証局を信頼するをご覧ください）、ほかに設定するものはなく、 そのまま検証が通ります。

お使いの CA を一度も信頼したことがない端末でも、これらのエンドポイントを検証できます。 Town OS は、自分が権威を持つゾーンの中に、証明書を固定する DANE レコードを _853._tcp.dns.<tld> と _853._udp.dns.<tld> の両方に公開します。 トランスポートごとに一つずつ置くのは、DANE に対応したクライアントが、自分の選んだトランスポートの レコードを見つけられないと接続を拒否してしまうからです。その端末はこのリゾルバーに到達できるのですから、 固定情報も取得でき、事前に何もインストールすることなく、渡された証明書を確かめられます。

DDR に対応したクライアントは、これらを自分で見つけます。Town OS は _dns.resolver.arpa（RFC 9462）に指定レコードを公開し、DoH の URL と DoT・DoQ の ポートを、その優先順で示します。DoH が先頭なのは、853 を遮断するフィルタリングでもポート 443 なら 通り抜けられるからです。DDR 対応の端末を通常の DNS としてこの機器に向けておけば、 あとは自分で暗号化エンドポイントを見つけて切り替えます。

この三つのリスナーは、起動時にインストールイメージの設定から開かれます。そのため、ほとんどの DNS 設定とは 異なり、ダッシュボードから有効にすることはできません。その背後にある証明書は、機器が動いてさえいれば バックグラウンドで更新され、再起動は要りません。新しい DANE の固定情報は古いものを取り下げる前に 公開されるので、検証するクライアントが接続を拒む瞬間は生じません。

悪意あるドメインをブロックする

rolodex はすべての問い合わせを公開ブロックリストと照合できるので、 別途 Pi-hole を用意しなくてもネットワーク全体で脅威をブロックできます。 設定は DNS → ブロックリストで管理します。プロバイダーには 2 種類あり、それぞれ対象が異なります。

• DNSBL（ドメインのブロックリスト） — 問い合わせられた名前と照合します。普段のウェブ閲覧に効いてくるのはこちらです。
• RBL（Realtime Blackhole List） — IP アドレスと照合し、逆引き DNS の問い合わせにのみ適用されます。

どちらも既定では無効で、プロバイダーの一覧も空です。また、どちらも 必要になったときにだけ問い合わせます。Town OS がブロックリストのフィードを ダウンロードしたり、解析したり、あらかじめキャッシュしたりすることはありません。 カテゴリーを有効にしてゾーンを 1 つ以上追加するまで、何も照合されません。

DNSBL の照合の仕組み

解決しようとしている名前がプロバイダーのゾーンの前に付けられ、通常の DNS 問い合わせとして照会されます。dbl.spamhaus.org を有効にした状態で badsite.example を解決すると、 badsite.example.dbl.spamhaus.org への問い合わせが発行されます。

• 応答があれば掲載されている — プロバイダーは掲載されている名前に対してアドレスレコード（通常は 127.0.0.x）を返します。rolodex はそのとき、問い合わせた端末へ NXDOMAIN を返します。
• NXDOMAIN なら問題なし — 解決は通常どおり続きます。エラーやタイムアウトを起こしたプロバイダーは、掲載されていないものとして扱われるため、到達できないブロックリストがネットワークを止めることはありません。
• ブロックリストは外の世界には勝つが、自分のレコードには勝たない — 照合はローカルとパッケージのレコードのあと（したがって gitea.default.home は常に解決されます）、上位のキャッシュとフォワーダーの前に行われます。そのため、転送された応答がすでにキャッシュされていても、掲載されている名前は拒否されます。
• 照合は名前単位で、サフィックス単位ではない — doubleclick.net が掲載されていても、プロバイダーがその名前も掲載していない限り stats.g.doubleclick.net はブロックされません。1 つのホストが掲載されたことでドメイン全体を落とすかどうかは、フィードではなくあなたが決めることです。
• 結果は短時間キャッシュされます — 掲載はプロバイダーの TTL の間、問題なしの結果は 5 分間です。

DNSBL のプロバイダー

以下はダッシュボードでワンクリックで追加できるものです。いずれも現在も稼働中で、 無料であり、登録の手続きなしに自前で再帰解決するリゾルバーへ応答します。Town OS の マシンはまさにそれに当たります。ほかのゾーンを手で入力することもできます。

RBL の照合の仕組み

IP アドレスを逆順にして、プロバイダーのゾーンの前に付けます。 192.168.1.100 を zen.spamhaus.org で確認すると、 100.1.168.192.zen.spamhaus.org への問い合わせが発行されます。IPv6 アドレスは ニブル単位に展開してから同じように逆順にします。応答があれば掲載、NXDOMAIN なら問題なしで、結果は DNSBL とまったく同じようにキャッシュされます。

注意点として、RBL のゾーンは逆引き DNS の問い合わせ （in-addr.arpa と ip6.arpa）に現れた IP に対してしか 参照されません。そして普通のウェブ閲覧では、そうした問い合わせはほとんど 発生しません。これらのリストは、メールサーバーが接続してきた送信者を拒否するために 存在し、そこでこそ役に立ちます。家庭用ルーターではほぼ何もしないに等しく、実際に閲覧に 効いてくるのは上記の DNSBL のほうです。Town OS の背後でメールサービスを運用している なら有効にしてください。そうでなければ、注目すべきはドメインのリストです。

RBL のプロバイダー

あえて用意していないリスト

よく知られた 3 つのゾーンは、意図的にワンクリック追加の一覧から外しています。 いずれも静かに失敗するためです。プロバイダーが設定されているのを見て、 守られていると思い込んでしまいます。仕組みを理解しているなら、手で追加することは できます。

• SORBS（dnsbl.sorbs.net） — 2024 年 6 月 5 日に運用を終了し、ゾーンは空になりました。応答はしますが、何も掲載されません。保護されているように見えて、実際には永久に何もしない状態です。
• Barracuda（b.barracudacentral.org） — 無料ですが、問い合わせ元の IP をあらかじめ登録する必要があります。未登録のマシンはしばらく使えたあと、予告なく遮断されることがあります。
• UCEPROTECT のレベル 2 と 3 — ネットブロックや AS 単位で掲載するため、同じ ISP に迷惑な利用者が 1 人いるだけで ISP 全体がブロックされます。

ローカルの登録と許可リスト

• ローカルの登録（DNS → ブロックリスト） — 特定のドメインや IP を、理由を添えて手動でブロックします。ドメインの登録は正引きに対して NXDOMAIN を返し、即座に反映されます。これは外部のどのプロバイダーよりも先に照合されるので、フィード全体を導入せずに特定のホストだけをブロックしたいときに使います。
• 許可リスト（DNS → 許可リスト） — 誤検知からの逃げ道です。許可された名前は、名前ベースの照合を丸ごと飛ばします。DNSBL のプロバイダーにもローカルの登録にも照合されず、プロバイダーへの問い合わせも一切発行されません。ブロックとは違い、許可はサフィックス単位で照合されます。vendor.example を許可すると cdn.vendor.example も許可されます。登録できるのは名前だけで IP は登録できないため、逆引き IP の RBL の経路には影響しません。

期待できること

これらのフィードはメール向けに作られており、広告向けではありません。 フィッシング、マルウェア、スパムのペイロードとなるドメインには非常に有効ですが、 広告やトラッカーに対しては平凡です。そちらはダウンロード型の hosts 形式のフィードの 仕事であり、Town OS はそれを意図的に取り込みません。定期的な取得も、解析も、 知らないうちに行われるキャッシュもありません。特定の広告やトラッカーのドメインを 消したい場合は、ローカルの登録として追加してください。

DNS でサービスを公開する

既定では、インストール済みのすべてのパッケージのサービスが、その ネットワークの TLD の下に DNS で公開されるため、 名前でアクセスできます。DNS → サービスでは、サービスごとに公開を 切り替えられます。非公開にしたサービスは動き続けますが、名前では解決できなくなります。 各サービスの完全修飾名は <name>.<repo>.<tld> の形式です（既定のネットワークでは TLD は .home です）。

ネットワークとリモートアクセス

Town OS はサービスをネットワーク単位でまとめます。どのマシンにも home という組み込みのネットワークが最初からあります。これは LAN 専用で、 .home の下の名前を解決し、トンネルは持ちません。自宅の外から安全に サービスへアクセスするには、ネットワークを追加してください。追加したネットワークは それぞれ、独自の DNS の TLD と対になった WireGuard のオーバーレイで、 ダッシュボード → ネットワークから管理します（管理者のみ）。

既定のネットワーク

• 常に存在し、削除できません。 home ネットワークは自動的に作成され、ほかを選ばない限りパッケージはここに配置されます。
• ローカル専用です。 WireGuard の経路を持たないため、.home の名前は LAN 上でのみ解決され、リモートのピアには意図的に一切公開されません。
• .home の TLD を使います。これは dns_tld 設定から来ています。

リモートアクセス用のネットワークを作る

ネットワークを作成をクリックし、名前（例: office）と、 任意で TLD（既定はネットワーク名）を指定します。すると Town OS は次を行います。

• 10.64.0.0/10 の範囲から決定的に導いたオーバーレイのサブネットで WireGuard インターフェースを生成し、マシン自身を .1 のアドレスにします。
• そのネットワークの TLD を確保します（TLD はマシン内で一意です。ほかのネットワークがすでに持つ TLD でネットワークを作ろうとすると拒否されます）。
• オーバーレイ上でネットワークごとの DNS リゾルバーを動かし、参加した端末がそのネットワークの名前を解決できるようにします。

各行のリモートアクセスのスイッチで、WireGuard インターフェースを 起動・停止できます。オフにすると、コンテナーは動いたままローカルからは到達できる状態で、 リモートアクセスだけが遮断されます。

端末を登録する

ネットワークのピアダイアログを開き、端末名を入力して ピアを追加をクリックします。Town OS はそのまま取り込める WireGuard の 設定を返すので、スマートフォンやノート PC の WireGuard アプリに貼り付けてください。

設定はその場でコピーしてください。そこには生成されたばかりの秘密鍵が 含まれており、保存されることはありません。あとから取得することはできず、 失った場合は端末を登録し直す必要があります。

生成された設定は端末の DNS をマシンのオーバーレイアドレスに向けるので、トンネルが つながればネットワークの名前が自動的に解決されます。通常の端末では rolodex DNS を実行するのスイッチはオフのままにしてください。 オンにするのは、転送先にしたい rolodex DNS サーバーをそのピア自身が動かしている 場合だけです。

WireGuard 専用アカウント

ダッシュボード全体を触らせずに、自分の端末だけを登録してもらいたい場合は、 WireGuard 専用アカウントを作成します（ユーザー作成画面の チェックボックスです）。このアカウントは、

• 特定のネットワークに限定されます — そのネットワークでのみピアを登録でき、home ネットワークには決して登録できません。
• フェイルクローズです。認証、自分のピアの登録と更新、CA の取得はできますが、コントロールプレーンのそれ以外の操作は一切できません。
• 期限付きのピアを登録します。登録ごとに TTL（既定は 2 時間、設定 → WireGuard ピアの TTL で変更）があり、接続を保つには更新が必要です。放置された端末は自動的に期限切れになります。管理者が追加したピアは恒久的です。

ピアの監視と切断

ネットワークのページにある接続中のピアのパネルには、すべての ネットワークにまたがる登録済みのピアが、ハンドシェイクの状態、オーバーレイの IP、 転送量、期限とともに一覧表示されます。端末を強制的に切り離すには 切断を使います。ピアが削除され、トンネルは直ちに落とされ、鍵は 失効するため、その端末は再び登録されるまで接続できません。

ネットワークを指定してパッケージをインストールする

インストールのダイアログ（および ページのダイアログ）には ネットワークの選択欄があります。 どのネットワークを選ぶかによって、そのサービスの DNS 名と TLS 証明書が決まります。office に インストールしたパッケージは .office の下で解決され、証明書もその名前で 発行されます。既定以外のネットワーク上のサービスはデュアルホームになり、トンネル越しの ピアにはオーバーレイのアドレス、ローカルのクライアントには LAN のアドレスとして 解決されます。別のネットワークでパッケージを入れ直すと、DNS と証明書もその ネットワークの TLD へ移ります。

たとえば fart という TLD のネットワークに Jitsi をインストールすると、 jitsi.default.fart で公開されます。起動すると、そのサービスは ダッシュボードにそのアドレスへのリンクとして表示され、ネットワーク上の どの端末からでも開けます。

USB イメージから VM を作る

install リポジトリには、Town OS を仮想マシンで起動するためのスクリプトが含まれており、 テストや開発に便利です。ソースからビルドした イメージからでも、すでに書き込んだ物理 USB メモリから 直接でも起動できます。 make help にすべてのターゲットと変数が載っています。

QEMU

make qemu-fg

イメージが古ければビルドし直したうえで、シリアルコンソールを接続し、KVM による アクセラレーションと、ストレージのテスト用の 4 台の仮想データディスクを備えた QEMU の VM をフォアグラウンドで起動します。まずはこのターゲットを 使ってください。起動とインストーラーの様子を端末上で直接確認でき、Ctrl-C で VM を 止められます。バックグラウンドで動かしたい場合は make qemu を使い （あとから make serial で接続します）、 停止・クリーン・再ビルド・再起動を一度に行うには make rebuild-qemu を使います。

VM は virbr0 上の libvirt の default NAT ネットワークに接続され、 VM_IP（既定は 192.168.122.50）に固定されるため、同時に動かす VM にはそれぞれ別のアドレスを割り当ててください。

ゲストは NAT 配下にあるため、VM_LAN=1（既定）は制御 API （5309）、UI（80/443）、ssh （2222）、WireGuard の UDP ポートを、ホストの LAN アドレスから ゲストへ中継します。これにより、Android クライアントを 動かしているスマートフォンから VM へアクセスできます。中継を無効にするには VM_LAN=0 を設定します。

物理 USB から起動する（qemu-usb）

make qemu-usb USB_DEV=/dev/sdX

ビルドしたイメージではなく、書き込み済みの物理 USB メモリから直接 QEMU を フォアグラウンドで起動します。書き込んだばかりのメモリが実際に起動するかを 確かめるのに便利です。デバイスは読み取り専用（スナップショット）で 開かれるため、ゲスト側の書き込みは破棄され、実際の USB は変更されません。 ストレージのテスト用に 4 台の仮想データディスクも接続されます。このターゲットは 何もビルドしません。install リポジトリをクローンし、install.sh か make flash でメモリに書き込んでから、USB_DEV をそれに 向けてください。x86_64 のホストでは、TARGET=aarch64（または rpi）を指定するとシステム全体のエミュレーションでメモリを起動できるので、 対応するハードウェアがなくても別アーキテクチャのイメージをテストできます。

停止と後片付け

# VM を停止する
make stop

# VM を停止し、イメージと仮想ディスクを削除する
make clean

環境変数

シリアルコンソール

# VM のシリアルコンソールに接続する
make serial

# または socat で手動で接続する
socat -,rawer,escape=0x1d unix-connect:/tmp/town-os-serial.sock

# Ctrl-] で切断

VM を見つける

# VM の IP アドレスを取得する
make vm-ip

# またはホストから mDNS で接続する
ssh root@town-os.local

RAID のインストール

ディスクのプロビジョニングは、初回起動時に ttyforce が対話形式で行います。ストレージはすべて btrfs を使います。

RAID の自動選択

ttyforce は利用できるディスクを検出し、転送方式（NVMe、SATA など）とサイズの近さで グループ化してから、ディスクの台数に応じて RAID レベルを自動的に選びます。

• 1 台 — single モード（冗長性なし）
• 2 台 — RAID 1（btrfs のミラー）
• 3 台以上 — RAID 5（btrfs のパリティ付きストライプ）

既定のマウントポイントは /town-os です。ttyforce は overlayfs 互換の 永続化のために @etc と @var のサブボリュームを作成します。

ディスクの検出

ttyforce は利用できるストレージデバイスを自動的に検出します。NVMe ドライブ、 SATA/SAS ドライブ、SD カードを識別する一方で、起動元の USB デバイスとリムーバブル メディアは除外します。この検出により、Town OS が起動元のドライブに触れることは 決してありません。

オーバーレイファイルシステム

ストレージのバックエンドにかかわらず、Town OS は /var と /etc の永続化にオーバーレイマウントを使います。下位のレイヤーは squashfs のルートから来ており、上位のレイヤーは RAID/ZFS のストレージ上にあります。 これにより、ベースの OS はイミュータブルなまま、システムの設定とサービスのデータは 再起動をまたいで保持されます。

静的サイトのホスティング

コンテナー化されたパッケージ以外に、Town OS には静的サイトのホスティングが 組み込まれています。常時有効で、ダッシュボード → ページから 管理します。各ページはイングレスの背後にある共有のウェブサーバーが配信し、 パッケージと同じようにネットワークの TLD の下で DNS 名と TLS 証明書を得ます。

コンテンツのソース

ページを作成するときは、名前、ドメイン （既定は名前と同じ）、ネットワーク（既定は home）と、 3 種類のコンテンツソースのいずれかを選びます。

• アーカイブのアップロード — サイトの tarball をアップロードします。アーカイブをアップロードするまで、ページは保留状態で待機します。
• git リポジトリ — リポジトリの URL からクローンします。ブランチを指定できるので（既定は main）、gh-pages に公開しているサイトにも便利です。
• コンテナーイメージ — OCI イメージからディレクトリを取り出します。

git とコンテナーのページは非同期にプロビジョニングされます。一覧には プロビジョニング中…のバッジが表示され、有効かエラーに変わります。 git とコンテナーのページで最新のコンテンツを取得するには再ビルドを 使います。アーカイブのページの場合は、新しい tarball をアップロードしてください。

ページの配信のしくみ

各ページは専用のストレージのサブボリューム上にあり、ポート 80 の HTTP で直接配信されます。 一方、パッケージのサービスはポート 80 を HTTPS へリダイレクトします。ページはネットワークを 持つため、その名前はネットワークの TLD の下で解決され、LAN から、そしてネットワークが WireGuard のオーバーレイであれば登録済みのリモート端末からもアクセスできます。

パッケージを作る

Town OS のパッケージは、コンテナー化されたサービスの動かし方を記述した YAML ファイルです。 完全な仕様はパッケージング形式のリファレンスを 参照してください。この節では実際の作業の流れを説明します。

リポジトリの構造

パッケージリポジトリは、packages/ ディレクトリを持つ git リポジトリです。 各パッケージは、バージョンごとの YAML 定義を収めたサブディレクトリを持ちます。

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

パッケージ定義を書く

最小限のパッケージに必要なのは image フィールドだけです。一般的な パッケージには、説明、ネットワーク、ボリューム、利用者向けの質問が含まれます。

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

質問には、自由入力のテキストや port のほかにもいくつかの型があります。 secret（空欄なら自動生成）、boolean（チェックボックスとして表示）、 oauth（提供元のデバイスフローを実行してトークンを取得する 接続ボタン）などで、どの質問も optional: true を指定すれば 空欄のままにできます。すべての一覧は、パッケージング形式のリファレンスの 質問を参照してください。インストール時には、 そのパッケージを提供するネットワークも 運用者が選びます。

テンプレートの仕組み

質問の回答や組み込み変数（@LOCAL_EXTERNAL_HOST@、 @LOCAL_INTERNAL_HOST@）を参照するには @variable@ 構文を使います。 テンプレートは環境変数、ポートマッピング、クォータ、ノートの値で機能します。

ローカルでテストする

パッケージのテストには開発環境を使ってください。 リポジトリをディスク上に置き、UI か repositories.json から追加して、 自分のパッケージをインストールします。開発環境は、テスト用に Town OS のスタック一式を 提供します。

リポジトリを追加する

自分のパッケージリポジトリは、UI から （パッケージ → リポジトリ → リポジトリを追加）、または repositories.json を直接編集して Town OS に追加します。

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

開発環境とテストスイート

Town OS の開発環境は、Podman のコンテナーを使ってスタック一式をローカルで動かします。 変更の確認、パッケージの開発、テストスイートの実行を行うには、これがいちばん速い方法です。

事前に必要なもの

• Linux — btrfs と Podman の rootful コンテナーに必要です
• Podman — コンテナーランタイム（sudo を使う rootful モード）
• Go 1.25 以降 — バックエンドの API サーバー用
• Bun — フロントエンドのビルドと開発サーバー用
• btrfs-progs — ストレージ管理用
• QEMU — VM パッケージのサポートに必要な qemu-system-x86_64 と qemu-img
• libsystemd — systemd 連携のための開発用ヘッダー
• golangci-lint — Go の lint 用
• Python 3 — ビルドとテストのスクリプト用

開発環境を起動する

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

これでホットリロード付きの開発スタック一式が起動します。準備ができたら、端末に 表示された URL を開いて Town OS のダッシュボードにアクセスしてください。

開発環境のコマンド

テストを実行する

統合テスト

統合テストは、実際の btrfs ファイルシステム、systemd、Podman-in-Podman を備えた 特権付きの Podman コンテナー内で実行されます。これにより、本番環境のインストールと 同じコード経路をテストできます。テスト用コンテナーは使い捨てで、テスト実行ごとに 新しく作られ、終了後に片付けられます。