パッケージング形式

パッケージ定義

利用できるフィールドをすべて使った、コンテナーパッケージの完全な定義例です。

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

image フィールドは文字列による省略記法も受け付けます: image: nginx:1.26-alpine。

image フィールド

image フィールドは実行するコンテナーイメージを指定します。書き方は 2 通りです。

# オブジェクト形式
image:
  url: nginx:1.26-alpine
  type: oci                # 任意。既定は "oci"

# 文字列による省略形式
image: nginx:1.26-alpine

短いイメージ名はコンパイル時に自動的に正規化されます。

type に指定できる値は oci（既定）だけです。イメージ URL に使えるのは 英数字と @、.、_、:、 /、- のみで、シェルのメタ文字は拒否されます。

ネットワーク設定

ポートの値は、テンプレート置換後に 1 から 65535 までの整数である必要があります。 使わない場合は external、internal、domains ごと省略してください。空のマップやリストは書かないでください。

ポートエントリーのキーは、数値のポート文字列 （"2222": "22"）か、^[a-zA-Z][a-zA-Z0-9_]*$ に一致する 意味的な名前（http: "3000"）のいずれかです。ポートに名前を付けると、 親パッケージは番号ではなく役割で参照でき（@dep_KEY_port_http@）、 特別な名前 http の場合は、後述する共有 HTTP イングレスの対象になります。

HTTP イングレス（http という名前のポート）

Town OS はポート :443 上で単一の共有イングレスを実行し、 すべてのパッケージの TLS を終端して、パッケージの平文 HTTP のコンテナーポートへ リバースプロキシします。パッケージは内部ポートに http という 名前を付けることでイングレスに参加します。

network:
  internal:
    http: "3000"      # コンテナーの平文 HTTP ポート

こうすると、次のようになります。

• サービスには https://<PACKAGE_DNS>/ でアクセスできます。 URL にポートは付きません。選ぶべきホスト側ポートもありません。 HTTP ポートを external にも割り当てないでください。
• イングレスは <PACKAGE_DNS>（例: gitea.default.home）に対してローカルで信頼されるリーフ証明書 （内蔵の Rolodex CA が発行）を提供します。さらに Rolodex は _443 上に DANE の TLSA レコードを公開するため、 DANE に対応したクライアントは証明書をピン留めできます。
• イングレスが :443 を占有するので、アプリが生成する URL は ポートなしの HTTPS でなければなりません。アプリの公開 URL を それに合わせて設定し（例: gitea の GITEA__server__ROOT_URL: "https://@PACKAGE_DNS@/"）、 アプリ自身はコンテナー内で平文 HTTP を待ち受けたままにしてください。

HTTP 以外のプロトコル（SSH、データベースなど）には http という名前を 使ってはいけません。HTTP ではないため、イングレスで TLS を終端できません。 代わりに数値のマッピングでそのまま転送してください。

network:
  internal:
    http: "3000"          # :443 イングレスが前段に立ち、TLS を終端
    "@sshport@": "22"     # 素の TCP 転送。TLS で包まれることはない

インターネット向けの名前（domains）

既定では、イングレスはローカルで信頼される <PACKAGE_DNS> の名前だけを 提供します。加えて、公的に信頼される証明書でサービスをインターネットに 公開したい場合は、実際の FQDN を network.domains に列挙し、その名前の公開 DNS を このホストに向けてください。イングレスは列挙された各ドメインについて ACME（Let’s Encrypt）証明書を取得します。

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

アーカイブ

archives フィールドは、インストール時にコンテナーイメージからボリュームへファイルを取り出します。

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

インストール時や再調整時に対象のボリュームが空であれば、Podman がイメージを取得し、 一時的なコンテナーを作成して、指定されたディレクトリをボリュームへコピーします。

質問

質問は、パッケージのインストール中に表示される対話プロンプトを定義します。利用者の回答は、 定義全体にある @name@ というテンプレートの記号を置き換えます。

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

質問のタイプ

boolean 型の質問

boolean の質問はテキスト入力欄ではなくチェックボックスとして表示され、 回答は文字列そのものの true または false として置き換えられます。 チェックを外した状態もれっきとした回答なので、default: "true" の質問を 利用者がオフにすることもできます。明示的な false が既定値に優先します。

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

ファイルテンプレートから見えるのも正規化後の値なので、 {{ .Responses.metrics }} は true または false として描画され、 {{ if eq .Responses.metrics "true" }} で判定できます。

任意回答の質問

optional: true を宣言していない限り、すべての質問は空でない値で回答する必要があります。 これがないと、アプリケーションが本当になくても動かせる設定（SMTP リレー、API キーなど）を 素直に表現できません。作者は仮の既定値をでっち上げ、運用者が上書きしてくれることを 祈るしかなくなります。

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"

空欄のままにすると、任意回答の質問はその @marker@ の箇所を 空文字列に置き換えます。そのためアプリケーションからは、誰も選んでいない値が 設定されているのではなく、変数が空であるように見えます。自動生成が行われることもありません。 空欄のままの secret は空欄のままで、アプリケーションが律儀に認証を試みるような ランダム文字列にはなりません。

optional は type と組み合わせられます。回答された任意のポートは 引き続きポートとして検証され、空欄のものはコンパイル時に何も残しません。 boolean に指定しても意味はありません。チェックボックスは常に 2 つの値の どちらかに決まるからです。

OAuth の質問

アプリケーションによっては、提供元しか発行できない認証情報（Plex のアカウントトークン、 GitHub の個人トークンなど）で設定するものがあり、通常はターミナルでスクリプトを実行して 出力された値を貼り付けます。oauth の質問は、その手順をインストールダイアログから 実行します。運用者が接続をクリックし、ブラウザーのタブで承認すると、 返ってきたトークンがそのまま回答になります。

プロバイダーの登録簿はありません。質問には提供元自身の URL を記した oauth ブロックを持たせるので、デバイスフロー方式に対応した提供元であれば 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

URL、ヘッダー、フォームの値に含まれる {{...}} のプレースホルダーは、 extract で名前を付けたものと、{{client_id}} に解決されます。 後者は Town OS がフローごとに生成してすべての手順で送るランダムな識別子で、 Plex はこれに pin を紐づけます。

トークンは認証情報なので、そのように扱われます。パッケージ情報のパネルでは伏せ字になり、 コピーはできても表示されることはありません。他の回答と同様にキャッシュされるため、 再インストールやアップグレードの際は運用者を提供元へ送り返さずに再利用されます。

これらの URL を呼び出すのはブラウザーではなくシステムコントローラーなので、URL は https でなければならず、ループバック、プライベート、リンクローカル、CGNAT の アドレスに解決されてはいけません。この確認は実際に接続する時点と、リダイレクトのたびに 行われるため、パッケージがフローを悪用してコントローラーにホスト自身のネットワークへ アクセスさせることはできません。

ノート

ノートは、インストール後に表示されるキーと値のメタデータです。

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

依存関係

パッケージは他のパッケージへの依存を宣言できます。依存先は親の podman ネットワークを共有するため、 同じ依存ツリーにあるコンテナー同士は、podman の内蔵 DNS を通じてコンテナー名で直接 通信できます。

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

親パッケージは実行時に、依存ごとの環境変数を受け取ります。 TOWNOS_DEP_{KEY}_HOST（コンテナー名）と TOWNOS_DEP_{KEY}_PORT_{port}（コンテナー側のポート番号）です。 親は環境変数の値の中で @dep_KEY_host@ や @dep_KEY_port_N@ の テンプレート変数を使うこともできます（テンプレートの仕組みを参照）。

例: PostgreSQL への db 依存を持つ Mattermost パッケージは、 データソース URL の中でデータベースのホストを参照できます。

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

VM ランタイム

image の代わりに vm フィールドを指定すると、パッケージは コンテナーではなく仮想マシンを実行できます。

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

vm フィールドは image および proton とは併用できません。 VM のイメージは、コンテナーイメージのようには正規化されません。

コンパイル

コンパイルは、パッケージ定義と利用者の回答を、完全に解決された実行可能な構成へと変換します。 コンパイルのパイプラインは次の手順を実行します。

• すべての質問の回答を、宣言されたタイプに照らして検証する
• タイプ固有の検証を適用する（ポートの範囲、ホスト名のパターン、バイト数の解析など）
• すべての @variable@ テンプレートの記号を、解決した値に置き換える
• コンテナーイメージの URL を完全修飾の参照に正規化する
• インストール可能な状態まで解決したパッケージを生成する

VM パッケージの場合、メモリの文字列（2gb など）はバイト数に解析され、 CPU の既定値が適用されます。検証エラーはすべてのフィールドについてまとめて収集され、 一括で返されるため、利用者は 1 度の修正ですべてを直せます。エラーに 1 つずつ ぶつかることはありません。

インストールの流れ

パッケージのインストールは、決められた一連の手順で進みます。 ファイルの準備からサービスの起動まで、すべてがこの流れで処理されます。

• リポジトリのパッケージファイルから、インストール先ディレクトリへのハードリンクの作成
• 回答の保存（バージョン別と last のコピー）
• クォータと任意の UID/GID 所有者を設定したボリュームの作成
• アーカイブと git ソースからのボリュームの初期化（コンテナーランタイムのみ）
• テンプレートの適用（ファイルをボリュームへ描画）
• systemd ユニットの生成（コンテナーは Podman ベース、VM は QEMU ベース）
• ネットワーク状態ファイルの作成
• サービスの開始
• 成功時の last の回答の消去

ボリュームの扱いは、2 つの任意フラグで制御できます。

• reuse_volumes — 同じパッケージの以前のアンインストール済みバージョンのボリュームを再利用する
• import_from_version — 特定の以前のバージョンからボリュームを取り込む

インストールのプレビュー

インストールを確定する前に、何が作られるのかを事前に確認できます。 インストールプレビューのエンドポイント（POST /packages/install-preview）は、 変更を一切加えずに、予定されるインストール内容の要約を返します。

• 作成されるボリューム
• 割り当てられるポート
• アップグレードの情報（以前のバージョンからアップグレードする場合）
• ランタイムの種類（コンテナーまたは VM）
• 回答すべき質問があるかどうか
• VM パッケージの場合は VM の構成の詳細（イメージ、メモリ、CPU 数）

リポジトリの取り込み

パッケージリポジトリを作ったら、ウェブ UI かファイルシステム上の設定のどちらかで、 自分の Town OS インスタンスに追加します。

UI から追加する

Town OS のダッシュボードにログインし、パッケージへ移動して リポジトリタブを選び、リポジトリを追加をクリックします。 名前、git の URL、必要なら認証情報を入力してください。更新をクリックすると、 パッケージのメタデータをすぐに取得できます。

ファイルシステムから追加する

btrfs のパッケージデータディレクトリにある repositories.json を編集します。 このファイルはオブジェクトの JSON 配列です。

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

並び順には意味があります。パッケージ名が衝突した場合、後のエントリーが先のものを上書きします。 プライベートなリポジトリでは、URL に認証情報を埋め込んでください。変更を反映するには、 サービスを再起動するか、UI で更新を実行します。

スタイルの指針

• 空のマップ（environment: 、internal: 、volumes: ）は書かず、まるごと省略してください。
• 自由入力のテキストを受け付ける質問では type を省略してください。値のない type: を書かないでください。
• そのパッケージが何であるかを短くまとめた description を入れてください。
• よく知られたサービスを提供するパッケージでは、該当する機能タグを supplies に入れてください。
• 接続 URL やインストール後に重要となる情報を notes に入れてください。
• ポート、ホスト名、認証情報をインストール時に利用者が指定できるよう、@variable@ テンプレートを使ってください。
• Go テンプレートのロジックが必要な設定ファイルには templates を使ってください。一度しか書き込まれないため、利用者の編集が保持されます。