olares-chart

コードまたは任意のプロジェクトを Olares にデプロイする

共通の入口： スイート内のルーティング、アクティブなプロファイルの選択、プラットフォームのエントリーポイントについては、../olares-shared/SKILL.md を読み込んでください。オーサリング — from-compose、lint、package — に Olares は一切必要ないため、Olares なしで開始してください。作業がアップロード、インストール、またはその他のデプロイ手順に進んだ時点で、共通の認証ゲートを適用してください。ログイン、プロファイルの切り替え、トークンの保存、または認証の復旧が実際に必要になった場合にのみ、認証リファレンスを読み込んでください。

フラグと構文は olares-cli chart <verb> --help で確認してください。移植を始める前に、共通のOlares プラットフォームモデルを読んでください。チャートの判断は、ストレージ、uid-1000、名前空間、ミドルウェア、バージョンの仕様に左右されます。

特定の Olares 向けにビルドするには、最初のイメージビルドより前に、対象ノードのアーキテクチャを確認する必要があります。デプロイ時に確認するのでは遅すぎます。

移植の対象は Olares 1.12.6 以降です。マニフェスト／チャートのバージョンフィールドと依存関係フィールドを記述する前に、バージョニングを読み込んでください。

使用する場面

• リポジトリ／docker-compose／汎用 Helm チャートを Olares アプリに変換する、または OlaresManifest を検証する。イメージをパッケージ化する。ストレージ／ミドルウェア／エントランス／環境変数／GPU を設定する
• 自分の Olares にアプリをデプロイ／実行する（market upload + install）。olares-doctor でチャートに起因する根本原因が特定された後、チャートを編集、lint し、再デプロイする
• 公式のベースアプリで生成／チャットモデルを提供する、llm-init を統合する、または埋め込みアプリを適切な Market インストール先にルーティングする

このスキルは、チャートの変更を担当します。olares-doctor は実行時の根本原因を特定し、olares-market は公開済みアプリを管理し、olares-router はアプリの実行後にモデルを設定して呼び出し、olares-publish は公開リストへの掲載を準備します。

作業の流れ — 2 つの軸

アプリの移植は、固定された from-compose → lint → deploy のパイプラインではありません。これは、互いに独立しつつ連動する 2 つの軸をそれぞれの 準備完了 状態へ進め、制約が明らかになるたびに戻って対応する作業です（イメージに組み込まれた uid／パスはチャートのマウント／権限に影響し、デプロイ上の制約によってイメージの再ビルドが必要になることがあります）。固定のステップ 1 から始めるのではなく、アプリが現在どの状態にあるかに応じて着手してください。両方の軸が準備完了になったら、現在の Olares にデプロイします。アップロード + インストール + 診断を自動で繰り返すループです。

• パッケージ化 — イメージ： アプリを組み込み、プル可能でアーキテクチャに適したアーティファクトにします。Olares はイメージをプルするだけで、ビルドは行いません。
• デプロイ — チャート： lint に合格する OlaresManifest + テンプレートです。from-compose は、着手方法の1 つにすぎません。

最初の手順（パイプラインではありません）： パッケージ化とデプロイの状態表でアプリの現在位置を確認する → 制約が明らかになるたびに戻りながら、それぞれの課題を準備完了まで進める → 自分の Olares にデプロイする。

軸 1 — パッケージング（イメージ）

Olares はレジストリからイメージをプルし、ソースからビルドすることはありません。そのため、すべてのワークロードで、公開されていてノードのアーキテクチャに適合するイメージを参照する必要があります。イメージ作業はエージェント主導です。まず olares-cli cluster node list で対象の Olares ノードのアーキテクチャを特定し、次に開発者が使用しているレジストリ（Docker Hub / ghcr）を確認します。docker が使用可能でログイン済みであることを確かめ、自分でビルドしてプッシュします。手動で行うのは docker login のみで、認証されていない場合に限ります（references/olares-chart-image.md）。対象ノードのアーキテクチャ向けにビルドしてください（単一アーキテクチャ）。開発ホストの暗黙のデフォルトアーキテクチャは使用しないでください。マルチアーキテクチャは公開時に限り使用します。

対象アーキテクチャはビルドの入力値なので、特定を後回しにはできません。 spec.supportArch が示すのはチャートが対応を表明するアーキテクチャです。イメージを開いて実際のアーキテクチャを確認するものはありません。そのため、誤った推測はビルド、プッシュ、lint を通過し、クラスターで exec format error が発生して初めて明らかになります。また、Apple Silicon では、対象が特定されていないと、暗黙に arm64 になります。ノードを照会するか、開発者にアーキテクチャを確認してください。どちらもできない場合は、推測せずに質問してください。 まだ誰もデプロイしていないチャートに限り、対象は不要です。

パッケージングの状態	対応内容	準備完了の条件
Dockerfile がない（ソースのみ）	Dockerfile を作成し、ビルドしてプッシュする	—
Dockerfile はあるが、プル可能なイメージがない	ビルドしてプッシュする（Docker Hub または ghcr）	—
プル可能なイメージがある	アーキテクチャを確認し、対象の Olares ノード（olares-cli cluster node list）に適合しない場合は再ビルドする	すべてのワークロードに、プル可能でアーキテクチャに適合するイメージがある

軸 2 — デプロイ（チャート）

目標は、lint に合格する Olares チャートです。from-compose（kompose）は作成方法のひとつにすぎません。通常のリポジトリ、汎用 Helm チャート、または既存の Olares チャートでは、それぞれ別の手順から始めます（以下の状態表を参照）。ローカルでの作成（from-compose / lint / package）にログインは不要です。

デプロイの状態	対応内容	準備完了の条件
ソースのみ（compose なし）	コードから docker-compose を作成する（compose.md）	—
docker-compose がある	chart from-compose を実行してから調整する（from-compose.md）	—
汎用 Helm チャート（OlaresManifest なし）	OlaresManifest.yaml を手作業で作成して調整する（from-compose はスキップ）	—
Olares にアップロード済みだが、ローカルコピーが残っていない	market download <app> を実行して .tgz を展開し、そこから調整する（olares-market の「charts → チャート管理」を参照）	—
すでに Olares チャートである	そのまま検証に進む	chart lint に合格するチャート

自分の Olares にデプロイする（完了手順）

両方の軸が準備できたら、現在の Olares に自動でデプロイします。lint で確認できるのはチャートの構造上の妥当性です。アプリがイメージをプルし、ミドルウェアを接続し、running に到達することまでは確認できません。それを行うのがデプロイのループです。**lint に合格したら、質問せずに続行してください。**ログインを確認 → spec.supportArch と cluster node list の結果が適合することを確認 → パッケージ化 → market upload → market install -s upload --watch → 失敗した場合はログを取得 → 診断 → チャートを修正して再度 lint → 再試行します。アーキテクチャによるアップロード拒否は、マニフェストまたはイメージが変更されるまで解消されません。変更していないパッケージのバージョンだけを上げて再試行してはいけません。確認のために止まるのは、プロファイルが olares-shared の認証準備状況ゲートで失敗した場合（invalidated / never）に限ります。logged-in / expired の場合はどちらも続行します。手順の全容はreferences/olares-chart-deploy.mdを参照してください。

自分の Olares にデプロイする場合、lint に合格する限り、メタデータは仮のままでも構いません。機能面の調整（ストレージ / ミドルウェア / 入口）は引き続き必要です。

懸念事項の案内

from-compose が生成するのは、Olares アプリとして正しいとは限らないスケルトンです。この索引を使って、現在の移行で該当するリファレンスだけを読み込んでください。元の 18 項目の懸念事項は、すべて引き続き網羅されています。

すべての移植で確認する項目

トリガー	参照先
すべてのワークロードイメージをビルドまたは選択する	イメージ
プロセスの UID を決めてから、マウントされたボリュームの所有者を決める — 2 つの独立した問いです。以下を参照してください	実行時の ID
永続化、エントランス、メタデータ、ワークロードのレプリカを割り当てる	マニフェスト
設定とプラットフォームの値を割り当てる	環境変数、必要な場合に限り、続けてデフォルト値またはシステム値を参照してください
パスワード、API キー、生成されたキーを扱う	シークレット
マニフェスト／チャートのバージョンと依存関係を設定する	バージョン管理
チャートの変更後に検証する	Lint
対象の Olares 上でチャートが動作することを確認する	デプロイ

マニフェストのリファレンスでは、ストレージ、エントランス／ポート、ワークロード／レプリカ、メタデータの 4 つの項目を個別に扱います。イメージ、実行時の ID、環境変数、シークレット、バージョン管理、検証、デプロイと合わせて、これらがすべての移植で確認する 11 の項目です。

実行時の ID：2 つの問いに答える

Q1（最終的にプロセスが使用する UID）と Q2（プロセスが書き込むディレクトリの所有者）は独立しています。Q1 のどの回答も、Q2 のどちらの回答とも組み合わせられます。両方に答えてから、具体的な方法について実行時の ID のリファレンスを参照してください。

問い	回答	対応
Q1 イメージで実際に使われる UID はいくつですか？	1000	spec.runAsUser: true を設定します。プライマリ以外のワークロードでは、securityContext.runAsUser: 1000 も自分で設定します
	0 で、エントリーポイントが PUID／PGID を使って UID を切り替える	spec.runAsUser は設定せず、PUID=PGID=1000 を設定し、最終的なプロセスを確認します
	0 のまま root で実行される、または 1000 以外の UID	securityContext.runAsUser: 1000 を試します。アプリが動かなくなる場合は、イメージを再ビルドします
Q2 userspace マウントに書き込みますか？	いいえ	完了です
	はい	再帰処理を行わない init-permissions initContainer（beclab/ イメージ、コンテナレベルの runAsUser: 0）を追加します。PUID／PGID の方法を使う場合は、まず起動ログを確認してください。エントリーポイントがすでに処理していることがよくあります

厳守すべき 2 つのルール：実行時に chown -R を実行しないこと、明示的な root の securityContext を設定しないこと。唯一の例外は beclab/ のパーミッション用 initContainer です。

条件に応じて確認

トリガー	参照先
Compose にデータベース／キューが含まれる、またはアプリの依存関係が必要	ミドルウェアと依存関係
CUDA イメージ、モデルのプロビジョニング、共有モデルキャッシュ	GPU とモデル
生成／チャット、カスタム llm-init、または埋め込みのサービング	モデルルーティング、モデル運用、カスタム統合
モデルアプリケーションはすでに実行中だが、誤ったものを提供している	olares-router — チャートではなく、その中にあるカードを参照してください
GPU／アクセラレーターのスケジューリングモード、またはリソースの上限	アクセラレーター
アプリで Docker または Compose を実行する必要がある	DinD
1 つの高負荷なバックエンドで複数のユーザーに対応する	共有バックエンド
実行中のアプリに、覚えやすいルートまたはカスタム FQDN が必要	カスタム URL

全体の組み立て手順については、ワークフローを参照してください。

動詞インデックス

olares-cli chart のサブコマンドのみです（正確な情報源：--help）。それ以外はすべて Docker または兄弟スキルです。

動詞	機能	該当時に読むもの
from-compose（エイリアス：init）	compose ファイルを kompose で変換し、Olares チャートのひな形を作成します	from-compose.md
lint	Market の取り込みパイプラインでチャートディレクトリ／.tgz を検証します	lint.md
package	アップロード用にチャートディレクトリを <name>-<version>.tgz にパッケージ化します（helm package と同等で、helm バイナリは不要です）	workflow.md（D4）

特殊な移植パターン

このスキルの大半は、HTTP の入口を持つウェブアプリを想定しています。上流のアプリが当てはまらない場合は、まず既知のパターンに合わせてください。それでも判断が難しい場合は、公式の移植例を確認してください。

• ヘッドレス CLI／サービス（ウェブ UI なし） — 入口を向ける GUI がありません。ウェブターミナルのサイドカーを可視の入口として追加し、API／MCP ポートを invisible な内部入口として公開します。→ archetype-headless.md
• GUI デスクトップアプリ（ブラウザーストリーミング） — ウェブ UI のないネイティブ Linux デスクトップアプリです。ウェブデスクトップのベースイメージ（デフォルトは Selkies、旧型ハードウェア／静的 UI には KasmVNC）でラップし、可視のウィンドウ入口を HTTP :3000 に向け、オプションの iGPU／VAAPI アクセラレーションを .Values.deviceName でデバイス制御します。→ archetype-gui.md
• 文書化されたパターンが当てはまらない場合は、推測する前に beclab/apps で現在有効な移植例を確認してください：

gh search code --repo beclab/apps <keyword>      # find charts using a pattern (e.g. type: application, accelerator, appCommon)
# then browse https://github.com/beclab/apps/tree/main/<app> — its OlaresManifest.yaml + templates/

誤解を招く参照は避けてください。

• OAC ルートに .suspend（または .remove）制御ファイルがあるアプリ — 配布停止中、または配布終了済みです。現在の信頼できるパターンではありません。
• spec.subCharts[].shared: true + options.appScope.clusterScoped: true + appRef（ollamaserver／ollamav2 の形式）で共有を表現する共有／クラスター範囲のチャート。共有アプリのパターンは、これらではなく apiVersion: v3 のアプリからコピーしてください。shared.md を参照してください。

Gotchas（lint では検出できないこと）

lint が検証するのは構造であり、Olares の正しさではありません。上記の懸念事項の表に加え、以下の見落としには注意が必要です。これらへの対処はすべてご自身の責任です。

• metadata.name はチャートのフォルダー名および Chart.yaml の name と一致させ、^[a-z][a-z0-9]{0,29}$ にする必要があります。 metadata.appid は metadata.name と同じ値にしてください（from-compose が設定します）。4 か所すべてをまとめて変更してください。lint も market upload も metadata.appid を必須としていません。 この値がないチャートでも問題なく lint が通り、正常にアップロードされます。プラットフォームが値を決定的に補完するためです。それでも設定してください。ほかの何かに決められるフィールドは、後で読み違えることになります。不一致の値は、値がない場合よりも問題です。これは入口ホストを決める値ではありません。プラットフォームはアプリ名から入口ホストを導出するため、値を計算せず、settings apps list の URL 列から実際の値を確認してください。
• クラスターへのアップロードでは、spec.supportArch が現在のノードのアーキテクチャの少なくとも 1 つと一致する必要があります。 olares-cli cluster node list を実行して確認し、参照されているイメージが同じターゲットアーキテクチャに対応していることを確認してください。アップロード時に architecture_incompatible が報告された場合は、修正して再パッケージしてから再試行してください。cluster_arch_unavailable が報告された場合は、パッケージとバージョンを変更せず、ノード検出が復旧するまで待ってください。
• 宣言された .Values.userspace.appData／appCache／userData のマウントには、対応する permission フィールドが必須です。 ない場合、アプリデータのクロスチェックが失敗します。
• hostPath ボリュームとローリングアップデートには互換性がありません。 ホストマウントを、上記のユーザースペースボリュームに置き換えてください。
• 入口プロキシはすべてのリクエストを options.apiTimeout 秒（デフォルトは 15s）で打ち切ります。 長時間の LLM ストリーム、大きなアップロード、処理の遅いレポートは、ポッドが正常でも入口で打ち切られます（504／接続切断）。無効にするには options.apiTimeout: 0 を設定するか、上限のある大きな値を設定してください。負の値は「無制限」ではありません（15s にフォールバックします）。マニフェストの改善項目を参照してください。

安全性とエスカレーション

• lint が通った後のデプロイ／デバッグサイクルは、承認されたチャートタスクの範囲内です。そのアプリのインストール、アップグレード、再起動、アンインストール、クリーンインストールのたびに、改めて確認を取る必要はありません。各反復で確認を求めると、サイクルが面接になってしまいます。
• ログイン、レジストリの認証情報の不足、対象の曖昧さ、またはそのアプリのタスク範囲外の事柄があれば、作業を止めて引き継いでください。
• ユーザーが指定していないチャートは、ほかの誰かのアプリです。内容は確認しても、その上にデプロイしてはいけません。
• レジストリのパスワードをコマンドの引数に含めてはいけません。docker login --password-stdin または認証情報ヘルパーを使用してください。