ドキュメント · 1.0

kcell アプリ

この章では kcell メニューを説明します。keelOS 上で Docker アプリを動かす機能です。入れたいのは Jellyfin や Nextcloud のようなアプリであって仮想マシンではないので、普段は「アプリを選び、いくつか入力して、作成をクリック」するだけです。kcell は keel が作ります。

1. kcell とアプリ

• kcell は、keelOS 上で Docker を動かす専用の小さな仮想マシンです。ボリューム（アプリのデータ）はホストのストレージプール上のデータセットで、コンテナが公開するポートは kcell 自身の LAN アドレスにあります。
• アプリは kcell の中の compose プロジェクト（1 つまたは複数のコンテナ）です。テンプレートから作る（フォーム 1 枚で、YAML を書く必要はありません）ことも、compose ファイルを自分で書くこともできます。
• アプリを新規作成するとき、既存の kcell に入れることも、keel にそのアプリ専用の kcell を新しく作らせることもできます。最初は何もない状態なので、そのままアプリを新規作成すれば十分です。先に kcell を作る必要はありません。

注意：kcell にはストレージプールが必要です（ストレージを参照）。テンプレートのダウンロードやイメージの pull には、kcell がインターネットに出られることも必要です。§9を参照してください。

左メニューの kcell を開きます。ページ上部に全体のカード（タイトル kcell、右側に アプリを作成… と kcell を作成… の 2 つのボタン）があり、その下に kcell ごとのカードが並びます。

各 kcell カードの 1 行目には、名前、状態（実行中、停止、停止（チェックポイント）、失敗）、LAN アドレスが表示され、右側に 設定、起動（実行中は 停止、再起動）、削除 が並びます。カードには アプリ と イメージ の 2 つのタブがあります。

2. アプリの作成

1. ページ上部の アプリを作成…（または kcell カードの この kcell にアプリを作成…）をクリックします。
2. アプリを作成 ダイアログでテンプレートを選ぶか、カスタム compose…（compose ファイルを自分で書く。§8を参照）を選びます。
3. フォームに入力します。最初の項目はアプリ名で、以降はテンプレートによって異なります。データの置き場所（マウント）、環境変数、フロントドア経由で開くか、keelAuth でログインするか、などです。各テンプレートで入力する内容は、それぞれの説明を参照してください。
4. このアプリをどの kcell に置くかを選びます。既存の kcell のどれか、または 新しい kcell（アプリと同じ名前） です。新規作成を選ぶと、残りの項目（ネットワーク、アドレス、CPU、メモリ、Docker ディスク、ボリューム）は keel の既定値になり、詳細 をクリックすると変更できます。
5. 作成（既存の kcell に入れる場合は 保存して起動）をクリックします。keel が kcell を作成して起動し、イメージを pull してアプリを起動します。経過は デプロイ ダイアログに表示されます。

内蔵テンプレートは次のとおりです。Jellyfin、Emby、Plex、Navidrome、Audiobookshelf（メディアと音楽）、Nextcloud、Paperless-ngx、Immich、Vaultwarden、Syncthing（ファイル、書類、写真、パスワード）、Home Assistant、Uptime Kuma、Frigate、AdGuard Home、Pi-hole、qBittorrent、Open WebUI、Samba、フロントドア、写真受信箱（photo-inbox）。新しいテンプレートや追加されたテンプレートはマーケットからインストールします。§10を参照してください。

テンプレート一覧で、このホストにはなくマーケットにあるテンプレートはグレー表示で、角に インストール が付きます。クリックするとそのテンプレートだけをダウンロードし（数 KB）、インストール後に使えるようになります。ネットワークがなくマーケットのカタログを読めない場合は、ホストにあるものだけが表示されます。

注意：外部からアクセスするアプリ（Vaultwarden、Nextcloud、Paperless-ngx、Immich、フロントドア）には、keel がアプリごとに専用の kcell を割り当てます（画面に「……はネットワークに公開されるため、keel は専用の kcell を作ります」と表示されます）。ほかのアプリとは同居しません。1 つのアプリに問題が起きても、ほかのアプリに影響しないようにするためです。すでにほかのアプリがある kcell には、この種のアプリは追加できません。新しい kcell を選んでください。

3. データの置き場所：マウント

アプリのフォームの マウント には、そのアプリが使うディレクトリが並びます。各ディレクトリには役割があります。構成、キャッシュ、データ（メディアライブラリやドキュメントライブラリなど、ユーザー自身のデータ）です。各マウントには次のものを選べます。

• マウントしない（なくてもよいディレクトリ）。
• この kcell のボリューム：keel がボリュームを自動で作成する（「ボリューム xxx（自動作成）」と表示されます）か、新しいボリューム… で名前を付けて作成します。
• ホストの他のデータセット：ホストのストレージプールにすでにあるデータセットを、kcell のボリュームとしてマウントします。keel はそれを作成も削除もしません。ファイルを開く をクリックすると中のファイルを見られます。
• keelNAS の共有：keelNAS 上の共有をマウントします。keel は keelNAS にアカウントを持たないので、その共有を読める keelNAS ユーザー と パスワード を入力します。パスワードはこのアプリの compose ファイルに保存されます。keelNAS については NASを参照してください。

データ系のマウントには 読み取り専用 を指定できます（たとえば Jellyfin はメディアライブラリを読むだけでよい場合）。

ボリュームを新規作成すると、実行中の kcell にすぐ追加されます。すでに動いているコンテナには影響せず、再起動も不要です。アップグレード前に起動した古い kcell では、最初のボリューム追加時に一度だけコールド再起動が必要です（画面に案内が出ます）。それ以降は不要です。

以前に削除したアプリと同じ名前のアプリを作ると、元のボリュームが残っていて、中の古いデータがそのまま使われます。フォームにその旨が表示されます。最初からやり直したい場合は、先にアプリを削除するとき ボリュームも削除 にチェックを入れてください。§7を参照してください。

4. メモリのチェック

テンプレートには、アプリがおおよそどれだけのメモリを必要とするかが宣言されています。kcell にアプリを追加するとき、keel はその kcell にある既存アプリの必要量を合計します。

• メモリが足りていれば、フォームに「アプリに必要 … / kcell …」と表示されます。
• 足りなければ「先に kcell の設定でメモリを … 以上にしてから、アプリを追加してください」と表示され、追加できません。設定 でメモリを増やしてから戻るか、新しい kcell を選んでください。
• kcell を新規作成する場合、keel はアプリが必要とするメモリに合わせてサイズを決めます。

アプリの必要量より少ないメモリに無理に絞らないでください。メモリ不足でコンテナが強制終了されます。

5. iGPU トランスコードとフロントドア

iGPU トランスコード：Jellyfin などのアプリのフォームには iGPU トランスコード の項目があります（ホストの内蔵 GPU が VF に分割できる場合のみ）。チェックを入れると、その kcell にホストの内蔵 GPU の VF が 1 つ割り当てられ、コンテナ内で /dev/dri が使えます。次の点に注意してください。

• 内蔵 GPU の VF を持つ kcell では、停止 はシャットダウンと同じで、チェックポイントは保存されません。コンテナは終了し、次回の起動時に再起動ポリシーに従って再び起動します。
• 内蔵 GPU の VF の追加・削除を反映するには、kcell のコールド再起動が一度必要です。保存すると keel が再起動してからアプリを起動します。
• Jellyfin のトランスコードは自分で有効にします。ダッシュボード、再生、トランスコードで、ハードウェアアクセラレーションに VA-API を選び、デバイスに /dev/dri/renderD128 を指定し、ハードウェアエンコードにチェックを入れます。

フロントドア経由で開く（https）：外部向けの Web アプリは「フロントドア」を経由して https でアクセスできます。フロントドア自体はテンプレートアプリ（フロントドア、Caddy ベース）で、1 台のホストに 1 つだけインストールできます。

1. まずいずれかの kcell に フロントドア アプリをインストールします。ドメインとメールアドレスは任意で入力できます（ドメインとメールがあれば Let's Encrypt を使います）。入力しなければフロントドア自身の CA を使うので、ブラウザに http://<フロントドアのアドレス>/ca.crt を一度インストールしてください。
2. その後 Vaultwarden、Nextcloud、Paperless-ngx、Immich を作成するとき、フォームの フロントドア経由で開く（https） は既定でチェックされており、アプリには https アドレスが割り当てられます。
3. チェックを入れると、アプリ自体はフロントドアからの接続だけを受け付けます。LAN アドレスに直接アクセスするとファイアウォールで遮断されます。

フロントドアがまだない場合、フォームには「このホストにはまだフロントドアがありません。先に kcell に「フロントドア」アプリを追加すると……」と表示されます。

keelAuth でログイン：テンプレートによっては keelAuth でログイン の項目があります（ホストに keelAuth が必要です。アカウント、トークン、権限を参照）。チェックを入れると、keel が keelAuth にこのアプリ用のログインクライアントと 2 つのグループ（アプリ名と「アプリ名-admins」）を作成し、アドレス、シークレット、CA をアプリの設定に書き込みます。利用できる人（keelAuth のグループ） を選ぶと、選んだグループのメンバーが使えるようになります。そのうえで管理者が「…-admins」にメンバーを追加すると、そのアプリの管理者になります。利用可能な keelAuth がない場合、この項目には「このホストには利用可能な keelAuth がないため、keelAuth ログインは使えません」と表示されます。

注意：Vaultwarden の Web ボールトは https でしか動作しないので、keelAuth でログインするには フロントドア経由で開く と併用してください。

6. アプリ一覧、スナップショット、更新前に戻す

kcell カードの アプリ タブがアプリ一覧です。各行にはアプリ名（クリックするとコンテナとマウントを確認できます）、コンテナ数、ポート、次のボタンが表示されます。

• 変更：テンプレートから作ったアプリではフォームが開きます。compose ファイルを手で変更したアプリでは YAML エディタが開きます。
• 起動、停止、pull：それぞれ docker compose up、down、pull に対応し、出力はダイアログに表示されます。
• スナップショット、削除。

ポートはリンクになっていて、クリックすると http://<kcell の LAN アドレス>:<ポート>/ が開きます。ポートは既定では kcell 自身の LAN アドレスにだけ公開され、ホストのアドレスには公開されません。ホストのアドレスでも使いたい場合は、kcell の作成/設定で ホストのアドレスでも公開 にチェックを入れます。

スナップショット

アプリの スナップショット をクリックすると、そのアプリのスナップショット一覧が表示されます。時刻、理由（更新前、kcell の新システム前、毎日、手動）、対象のデータセットです。

• keel は、アプリの更新前に自動でスナップショットを作成します。compose ファイルが変更された後、または新しいイメージを pull した後の次の起動時、そして kcell が新しいシステムに切り替わる前（keelOS のアップグレード後）に、各アプリについて 1 つ作成します。スナップショットにはアプリ自身の構成系ボリュームと compose ファイルが含まれます。データ 系のライブラリ（メディアライブラリなど）とホスト上のデータセットは含まれません。それはあなた自身のデータであり、ロールバックで更新後に追加したものが消えてはならないためです。
• 毎日（UTC の日付ごと）にも別に 1 つ作成されます。keel の設定 kcell_daily_snap=false で無効にできます。各アプリで、更新前のスナップショットは直近 5 個、毎日のスナップショットは 7 個を保持します。
• これらのスナップショットには 保護 のマークが付きます。ホストで zfs destroy を使っても削除できず、kcell 内の root からも触れません。
• 今すぐ作成 で手動作成します。

更新前に戻す

アプリの更新で調子が悪くなったら、スナップショット一覧で戻したい行の 更新前に戻す をクリックして確認します。keel はまずアプリを停止し、ボリュームと compose ファイルをそのスナップショットまでロールバックしてから、再び起動します。ロールバック後は、それ以降にボリュームへ書き込まれたデータが失われ、そのスナップショットより新しいスナップショットも削除されます。経過は出力ボックスに表示されます。

7. アプリと kcell の削除

アプリの削除：アプリを先に停止し（コンテナ数が 0）、削除 をクリックします。ダイアログの ボリュームも削除 は既定ではオフです。オフならボリュームは残り、あとで同じ名前のアプリを作ると中の古いデータがそのまま使われます。オンにするとデータも一緒に削除され、元に戻せません。

kcell の削除：カードの 削除 をクリックします。実行中の kcell では 停止して削除 を選びます（先に通常どおりシャットダウンします）。ボリュームも削除 は既定ではオフです。オフならボリュームとアプリのディレクトリは保管場所に移して残され、あとで新しいアプリを作るとき「ホストの他のデータセット」から選び直せます。オンにするとすべて削除されます。

8. 自分で compose を書く

カスタム compose… を選び、エディタで compose ファイル（YAML）を書き、アプリ名 を付けて 保存 または 保存して起動 をクリックします。相対パス（./data）はホストの stacks/<アプリ名>/ の下に置かれます。kcell のボリュームはコンテナ内では /vols/<ボリューム名> です。

自分のコンピューターから docker を使うこともできます。kcell の 設定（詳細） に SSH 公開鍵を追加してその kcell をコールド再起動すると、カードの お使いのコンピューターから docker にコピーできるコマンド（docker context）が表示されます。LAN 上には 2375/2376 ポートはなく、SSH（鍵認証のみ）だけです。

イメージ タブには、その kcell にあるイメージが一覧表示されます（pull…、未使用のイメージを整理）。イメージはコンテナが動くための元ファイルで、インストーラではありません。コンテナが使っているイメージは削除できません。アプリの更新後に残った古いバージョンはコンテナが使っていないので、整理できます。

9. ネットワークとファイアウォール

• kcell を新規作成するとき、ホストに複数のネットワークがあれば ネットワーク（LAN NIC） を選べます。アップリンクのないネットワークではアドレスを取得できず、イメージの pull もできません。その旨は一覧に表示されます。アドレスは既定で DHCP ですが、固定 を選んで アドレス/プレフィックス長（例：192.168.1.20/24）と ゲートウェイ を入力することもできます。
• テンプレートには kcell の NIC のファイアウォールが付属しています。受信はテンプレートが宣言したポートだけを許可します（たとえば Vaultwarden は tcp/80 だけ、フロントドア経由なら フロントドアのアドレスだけ）。送信は既定でインターネットと DNS だけを許可し、LAN には通じません。keelAuth でログインするアプリには、keelAuth への通信が追加で許可されます。設定は不要です。
• Jellyfin、Plex のように LAN 内で発見される必要があるメディアアプリや、Home Assistant、Uptime Kuma のように LAN 内の機器に接続する必要があるアプリでは、テンプレートは制限を設けません。
• 自分で compose を書いて作った kcell にはこれらのルールはありません。

10. テンプレートの更新

keelOS には上記の基本テンプレートが同梱されています。新しいテンプレートや更新されたテンプレートは、マーケットの アプリテンプレート で 1 つずつインストールできます。アプリ作成時のテンプレート一覧でグレーのテンプレートの インストール を直接クリックしてもかまいません。インストールしたテンプレートパッケージは、現在の keelOS より新しい場合にだけ同名の内蔵テンプレートを置き換えます。パッケージを削除すると内蔵のものに戻ります。すでに作成したアプリには影響しません。

11. kcell の設定

kcell カードの 設定 をクリックすると 設定（詳細） が開きます。

• Docker ディスク：拡大のみ可能です（拡大後のサイズ）。Docker がどれだけ使っているかも表示されます。
• SSH 公開鍵：§8を参照してください。
• CPU、メモリ、LAN アドレス、メモ、ホストのアドレスでも公開 など。各項目の横に すぐに反映 か コールド再起動後に反映 が表示されます。コールド再起動が必要なものは、保存後に keel が今すぐ再起動するか確認します。再起動するとコンテナは終了し、再起動ポリシーに従って再び起動します。

アプリが必要とするより少ないメモリにすると、「アプリに必要なメモリ（…）より少ないため、コンテナがメモリ不足で強制終了されます」と表示されます。

起動 / 停止：停止 は kcell のメモリをチェックポイントに保存し、コンテナは終了しません。次回 起動 すると続きから動きます。内蔵 GPU の VF を持つ kcell は例外です。§5を参照してください。再起動 はコンテナを終了させ、再起動ポリシーに従って起動し直します。

12. 1.0 の制限

• 1 台のホストにフロントドアは 1 つだけです。
• kcell の Docker アプリ内のアカウントはアプリ自身が管理し、keel は管理しません（keelAuth でログインするアプリは除き、グループとクライアントを keel が作成します）。
• ストレージプールをライブマイグレーションした後、新しい場所のスナップショットには保護マークが付きません。