Keelson Deploy Spec

Spec version: 2025-03-14 / Raw text (AI向け): /ja/docs/reference/deploy-spec.txt

この文書は、Keelson にアプリをデプロイする際の対応ランタイム・制約・成立条件を定義する正本です。デプロイの可否判断は、この文書に従ってください。

クイックスタートや操作手順はデプロイするを参照してください。

デプロイ成功の定義

Keelson におけるデプロイ成功とは、ビルドが完了することではありません。次の条件をすべて満たした場合にのみ、デプロイは成功とみなされます。

アプリのビルドが完了している
アプリのプロセスが起動している
ヘルスチェックに通過している
アプリ URL（https://<slug>.keelson.run）が発行されている
アプリ URL にアクセスできる状態である

ビルドが成功しても、起動に失敗した場合やヘルスチェックに通らない場合は、デプロイ成功ではありません。

必須ファイル

すべてのデプロイには keelson.yaml が必要です。プロジェクトのルートディレクトリに配置します。

最小構成:

slug: my-app
runtime: python-slim
command: "pip install --user -r requirements.txt && python app.py"
env:
  PORT: "8080"

各フィールドの詳細は keelson.yaml リファレンスを参照してください。

対応ランタイム

Keelson は、以下のランタイム上でのみアプリを実行できます。

ランタイム	言語	用途
`python-slim`	Python	軽量。API、テキスト処理、自動化など
`python-media`	Python	メディア処理向け。画像・動画ライブラリを含む
`node-slim`	Node.js	軽量。Web アプリ、API など
`node-media`	Node.js	メディア処理向け。画像処理ライブラリを含む
`go-slim`	Go	軽量
`go-media`	Go	メディア処理向け

keelson.yaml の runtime フィールドで指定します。迷った場合は -slim から始め、メディア処理系ライブラリが必要になったら -media に切り替えてください。

slim と media の違い

slim — 言語ランタイムと標準ライブラリのみ。ビルドが速く、イメージサイズが小さい
media — slim に加え、画像処理（Pillow、sharp 等）や動画処理に必要なシステムライブラリがプリインストールされている

対応フレームワーク

特定のフレームワークに依存しません。command で起動でき、HTTP サーバーとしてリクエストを受け付けるアプリであれば動作します。

例: FastAPI、Flask、Express、Next.js、Hono、Gin など。

非対応ランタイム

以下の言語・ランタイムはサポート対象外です。

Ruby
Java / Kotlin / Scala
PHP
Rust
.NET / C#
Elixir / Erlang
Swift

非対応ランタイムのアプリは、修正や変換を行っても Keelson へデプロイできません。

ビルド環境と実行環境の制約

Keelson は固定されたビルド環境・実行環境を提供します。アプリはその環境上でビルドおよび起動できる必要があります。

OS・アーキテクチャ

OS: Linux
CPU: x86_64 (amd64)

root 権限

アプリは非 root ユーザーとして実行されます。sudo、apt-get install、システムレベルの変更は実行できません。

Dockerfile

使用できません。Keelson はランタイムを選択し、command で起動する方式です。Dockerfile の代わりに keelson.yaml でランタイムと起動コマンドを指定します。

ファイルシステム

パス	書き込み	永続化	用途
`/data`	可	`storage` 設定時のみ	SQLite、ファイルアップロード、アプリデータ
アプリディレクトリ	可（一時的）	不可	ソースコード、依存関係
`/tmp`	可（一時的）	不可	一時ファイル
その他	不可	—	—

再デプロイ時に /data 以外の書き込みは失われます
/data を永続化するには keelson.yaml の storage を設定してください
詳細は永続ストレージを参照

ポート

Web アプリは環境変数 PORT で指定したポートで HTTP リクエストを待ち受けてください
0.0.0.0 で listen する必要があります。127.0.0.1 や localhost ではリクエストが届きません
HTTPS 終端は Keelson が行います。アプリは HTTP で listen してください

システムパッケージ

Keelson は任意の OS パッケージ追加を前提とした環境ではありません。

-slim ランタイムには最小限のシステムライブラリのみ含まれます
-media ランタイムには画像・動画処理に必要な一般的なライブラリが含まれます
それ以外のシステムライブラリが必要な場合、アプリは動作しない可能性があります
apt-get 等によるパッケージ追加はできません（非 root のため）

プロセスモデル

command で起動した単一プロセスが基本です
systemd やデーモン管理は使えません
バックグラウンド処理が必要な場合は workers を使ってください

リソース

CPU とメモリはプランの Compute Class に応じて割り当てられます
アプリごとの個別設定ではなく、ワークスペース内の全アプリに共通の性能帯が適用されます

依存関係に関する制約

言語ランタイムが対応していても、依存ライブラリやシステム要件によってはデプロイできない場合があります。

言語パッケージマネージャで追加できる依存

以下のパッケージマネージャで管理される純粋な言語パッケージは問題なくインストールできます。

Python: pip（requirements.txt）
Node.js: npm（package.json）
Go: go mod（go.mod）

依存関係は command 内でインストールします。

# Python
command: "pip install --user -r requirements.txt && python app.py"

# Node.js
command: "npm install && npm start"

# Go (Keelson 側で deploy 時に `./app` がビルドされます)
command: "./app"

ネイティブ依存が必要なパッケージ

一部のパッケージは、C ライブラリやシステムレベルの依存を必要とします。

-media ランタイムで動作するもの: Pillow、opencv-python、sharp、ffmpeg 関連など、一般的なメディア処理ライブラリ
動作しない可能性があるもの: ランタイムに含まれないシステムライブラリに依存するパッケージ

サポート対象外になる典型パターン

パターン	理由
`apt-get install` が必要	非 root でパッケージ追加不可
特殊な C ライブラリに依存	ランタイムに含まれていない可能性
GPU を前提とした推論ライブラリ	GPU インスタンス未提供
データベースサーバー（PostgreSQL、MySQL、Redis）	外部サービスとして接続は可能だが、Keelson 上での起動は不可
systemd やバックグラウンドデーモン前提	プロセスモデルが異なる

デプロイモード

command と assets の組み合わせにより、デプロイモードが決まります。

モード	`command`	`assets`	説明
コンテナ	あり	なし	通常のアプリデプロイ
静的サイト	なし	あり（`fallback` なし）	静的ファイルのみ
SPA	なし	あり（`fallback` あり）	SPA（フォールバック付き）
ハイブリッド	あり	あり（`fallback` 必須）	静的ファイル + バックエンド API

環境変数とシークレット

アプリの起動に必要な API キー、トークン、接続情報は、コードに直接埋め込まず、環境変数またはシークレットとして設定してください。

keelson.yaml の env — バージョン管理に含めてよい値
コンソールのシークレット — API キーやトークンなど、コードに含めたくない値

必要な値が未設定の場合、アプリは正常に起動できないことがあります。

詳細は環境変数とシークレットを参照してください。

Keelson が自動設定する環境変数

変数名	説明
`TZ`	タイムゾーン（`Asia/Tokyo`）
`KEELSON_APP_ID`	アプリの内部 ID
`KEELSON_TENANT_ID`	テナントの内部 ID

タイムアウト

対象	制限
HTTP リクエスト	一般的なタイムアウトが適用
定期実行ジョブ（cron）	1〜3,600 秒（デフォルト 300 秒）
ビルド	制限あり（依存関係の量による）

外部通信

アプリから外部 API やサービスへの通信（Egress）はデフォルトで可能です
Business プラン以上では、通信先をホスト名単位で制限できます

よくある失敗パターン

症状	原因	対処
ビルド成功、起動後すぐ落ちる	`0.0.0.0` で listen していない	`host="0.0.0.0"` を明示
ポートに接続できない	ポート番号がハードコード	環境変数 `PORT` から読み取る
モジュールが見つからない	`command` に依存インストールが含まれていない	`pip install` / `npm install` を `command` に含める
ネイティブモジュールのビルド失敗	システムライブラリ不足	`-media` ランタイムに変更、または依存を見直す
`/data` に書き込めない	`storage` 未設定	`keelson.yaml` に `storage` を追加
起動コマンドが見つからない	エントリポイントのパスが間違い	ファイル名・パスを確認

失敗時の確認手順

ビルドログを確認 — 依存関係のインストールが成功しているか
実行ログを確認 — 起動時エラーやランタイムエラーがないか
keelson.yaml を確認 — runtime、command、env の設定が正しいか

AI エージェントの期待動作

AI エージェントは、Keelson へのデプロイ時に以下の順序で判断してください。

判断フロー

ランタイム確認 — アプリの言語がこの仕様の対応ランタイムに含まれるか確認する
依存関係確認 — ネイティブ依存やシステムライブラリの要件が制約内か確認する
keelson.yaml 確認 — ファイルの有無と設定内容の妥当性を確認する。なければ作成する
環境変数確認 — 必要な環境変数やシークレットが不足していないか確認する
デプロイ実行 — CLI または Skill を使ってデプロイを実行する
完了確認 — ビルド完了だけでなく、起動・ヘルスチェック・URL アクセスまで確認する
失敗時対応 — ログを確認し、修正可能な範囲で対処する。制約違反がある場合は理由を明示して停止する

必須ルール

非対応ランタイムの場合は、デプロイを試行しない。理由を明示して停止する
必須設定が不足している場合は、必要事項を提示する
ビルド成功のみで完了扱いにしない
起動失敗時は必ずログを参照する

仕様参照の優先順位

Web 上の最新 Keelson Deploy Spec（この文書）
Web 上の最新 CLI バージョン情報
Skill 同梱版の仕様
一般知識・推測

Web 上の正本と Skill 同梱の情報が矛盾する場合は、Web 上の正本を優先してください。