Keelson Deploy Spec

Spec version: 2026-09-02 / Raw text (AI向け): /ja/docs/reference/deploy-spec.txt

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

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

デプロイ成功の定義

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

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

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

必須ファイル

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

最小構成:

slug: my-app
runtime: python-slim
command: "python app.py"
db:
  mode: none

db と db.mode（libsql または none）は必須です。

Flask などのフレームワークを使うアプリには本番用サーバーが必要です。本番環境向けの設定を参照してください。

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

配置リージョン

アプリは作成時に 1 つの論理リージョンへ配置されます。リージョンの論理キーは jp-tokyo（日本）と us-oregon（米国西海岸）です。クラウド事業者のリージョン名ではなく、この表示名と論理キーを使います。

新規アプリでは keelson deploy --new --region <region>、または keelson.yaml のトップレベル region で配置先を指定できます。優先順位は CLI の指定、keelson.yaml、ワークスペースの既定リージョンの順です。rollout 中は一覧にあるリージョンでも新規作成に未開放の場合があり、未開放のリージョンを明示すると拒否されます。

リージョンはアプリ作成後に変更できません。既存アプリへ別のリージョンを指定しても移動は行われず、デプロイは拒否されます。別リージョンを使う場合は、新しいアプリとして作り直してください。

対応ランタイム

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`	不可（Keelson も作らず、アプリからも作れない）	不可	アプリは UID 1000 で実行され、root 所有の `/` 直下にはディレクトリを作れません
アプリディレクトリ	不可（書き込み先として使えません）	不可	ソースコード、依存関係
`/tmp`	可（一時的）	不可	一時ファイル
その他	不可	—	—

ローカルファイルへの書き込みはすべてエフェメラルで、再起動・scale-to-zero で失われます
永続データの置き場所は 3 つだけです: Managed SQLite（db.mode: libsql）、Files SDK（アプリ内部の非公開ファイル）、Media SDK（利用者に配信する画像・添付）。いずれもパスではありません
/data のファイル SQLite は永続化されません。ファイル SQLite クライアントの使用はデプロイ時に検出され、db.local_sqlite で一時用途と宣言しない限り拒否されます

ポート

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 やデーモン管理は使えません
バックグラウンド処理が必要な場合は crons を使ってください（workers は廃止済みで、宣言するとデプロイが拒否されます）

依存関係に関する制約

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

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

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

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

依存関係はイメージのビルド時に Keelson が自動でインストールします（requirements.txt / pyproject.toml / package.json / go.mod を検出）。command ではインストールせず、アプリの起動だけを行ってください。command に pip install / npm install / go build があると、CLI の事前チェックが command_installs_dependencies でデプロイを止めます。

ビルドの制約: Node のロックファイルは package-lock.json のみ。公開レジストリのみ（private registry・認証付きインストール不可）。Go は CGO_ENABLED=0。ビルド対象は linux/amd64。ビルド時にシークレットは渡らない。上限 900 秒。

# Python
command: "python app.py"

# Node.js
command: "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 という持ち物から自動的に決まる導出値です。CLI / API の出力は deploy_mode の生ラベルを返すため、対応表で読み替えてください。

呼称	`deploy_mode` 生ラベル	`command`	`assets`	説明
Web アプリ	`container`	あり	なし	通常のアプリデプロイ
静的サイト	`edge-static`	なし	あり（`fallback` なし）	静的ファイルのみ
SPA	`edge-spa`	なし	あり（`fallback` あり）	SPA（フォールバック付き）
ハイブリッド	`hybrid`	あり	あり（`fallback` 必須）	静的ファイル + バックエンド API

予約 URL パス

Keelson がアプリのホスト上で予約する URL 名前空間は /__keelson/* の 1 つだけです。それ以外のパスはすべてアプリのものです。/assets、/files、/static、/uploads、/api のような一般的なパスをプラットフォームが奪うことはありません。

/__keelson/* はプラットフォーム内部用です。プラットフォームが配信するアセット・ファイルダウンロード・内部エンドポイントに使われます。この配下にアプリのルートを定義しないでください。
ビルド出力の配信ルート直下に __keelson ディレクトリを出力しないでください。 予約パスを含むビルドはビルド時にエラーコード reserved_path_conflict で拒否されます。ディレクトリ名を変更して再デプロイしてください。
それ以外は予約されていません。 /assets/*（Vite の既定出力先）などのフレームワーク既定パスは、設定変更なしでそのまま配信されます。
関連ルール: auth.endpoints のパスは /__keelson で始められません（/api/external/ または /api/webhooks/ で始める必要があります）。また slug に予約語は使えません。

フレームワーク静的パス衝突マトリクス（参考）

主要フレームワークが既定で出力する静的パスの一覧です。いずれも /__keelson/* とは衝突しません。参考情報であり、実測 = 本リポジトリで確認済み、それ以外は 要検証（知識ベースの推定。根拠として使わず、必要なら確認すること）です。

フレームワーク	既定の静的パス	`/__keelson` と衝突	状態
Vite（Vue / Svelte / React / Solid / Preact）	`/assets/*`	しない	実測
Remix v2 / VitePress	`/assets/*`	しない見込み	要検証
Angular	`/assets/*`	しない見込み	要検証
Next.js	`/_next/static/*`	しない見込み	要検証
Nuxt / SvelteKit / Astro	`/_nuxt/` · `/_app/` · `/_astro/*`	しない見込み	要検証
CRA / Django / Flask	`/static/*`	しない見込み	要検証

環境変数とシークレット

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

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

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

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

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

変数名	説明
`PORT`	アプリが listen するポート。読み取り専用で、自分で設定しない
`TZ`	ワークスペースのタイムゾーン。ワークスペース作成時にブラウザから自動決定される
`KEELSON_MODE`	Keelson 上で動作していることを示す印（値は `keelson`）
`KEELSON_APP_ID`	アプリの内部 ID
`KEELSON_WORKSPACE_ID`	ワークスペースの内部 ID
`KEELSON_TENANT_ID`	`KEELSON_WORKSPACE_ID` の互換用別名（値は同じ）
`KEELSON_DEPLOY_ID`	現在のデプロイの内部 ID

旧 tenant 名の変数も互換のため受け付けます。撤去時期は未定です。

db.mode: libsql のときは KEELSON_DB_URL / KEELSON_DB_AUTH_TOKEN（別名 TURSO_DATABASE_URL / TURSO_AUTH_TOKEN）が追加で注入されます。KEELSON_ で始まる名前はプラットフォーム予約で、env や secrets には使えません。

本番環境向けの設定

Keelson のアプリは Cloud Run 上で動作し、通常運用中にも起動と停止が発生します。停止時にはプロセスへ SIGTERM が送られ、10 秒後に SIGKILL が送られます。本番用サーバーを使い、この時間内にドレイン処理を完了してください。

フレームワーク別の本番サーバ

Flask: app.run() は Werkzeug 開発サーバーを起動します。ローカル用の __main__ エントリーポイントの中に残すことはできますが、debug=False でもデプロイ先のサーバーにしてはいけません。gunicorn を requirements.txt に追加し、次のコマンドを使います。

command: "gunicorn --bind 0.0.0.0:$PORT --workers 1 --threads 8 --timeout 0 --graceful-timeout 9 app:app"

Keelson は 1 vCPU のため、worker は 1 にします。graceful timeout を 9 秒にすると、10 秒の SIGTERM 猶予内に収まります。app:app はプロジェクトのモジュール名とアプリケーションオブジェクト名に置き換えてください。

Django: gunicorn で Django を起動します。

command: "gunicorn --bind 0.0.0.0:$PORT --workers 1 --threads 8 --timeout 0 --graceful-timeout 9 config.wsgi:application"

DEBUG は既定で無効にします。
DEBUG=False の場合、Django 自身は静的ファイルを配信しません。whitenoise を MIDDLEWARE に追加し、STATIC_ROOT を設定して、collectstatic 済みの成果物を配信対象に含めてください。
ALLOWED_HOSTS = ["*"] は維持してください。制限するとヘルスチェックが HTTP 400 になることがあります。
config.wsgi:application はプロジェクトの WSGI モジュールに置き換えてください。

FastAPI / uvicorn: 0.0.0.0:$PORT にバインドし、worker 数は既定の 1 のままにします。

command: "uvicorn main:app --host 0.0.0.0 --port $PORT"

--reload は使わないでください。ファイル監視がメモリを消費し、アプリが二重起動することがあります。main:app はプロジェクトのモジュール名とアプリケーションオブジェクト名に置き換えてください。

Next.js: 開発サーバーではなく、ビルド済みのアプリを起動します。

command: "npm run start"

package script は次のように設定します。

"start": "next start -p $PORT"

package.json に "start": "next dev" がある場合、回避策を加えるのではなく、その script を修正してください。next dev は本番用サーバーではありません。

Node.js: Keelson は NODE_ENV を自動設定しません。keelson.yaml で本番モードを宣言してください。未設定の場合、Express などのフレームワークがスタックトレースを返すことがあります。

env:
  NODE_ENV: "production"

Go: ビルド済みバイナリを command: "./app" で起動します。ListenAndServe を停止処理なしで放置せず、signal.NotifyContext と server.Shutdown を使って新規リクエストの受付を止め、処理中のリクエストを 10 秒の猶予内に完了させてください。

デバッグ・開発モードの既定

既定値は本番で安全な向きにします。Python の DEBUG は false を既定にします。

DEBUG = os.environ.get("DEBUG", "false").lower() == "true"

true を既定にしてはいけません。

DEBUG = os.environ.get("DEBUG", "true").lower() == "true"

デバッグ画面は、データベースの認証トークンを含む環境変数を表示することがあります。

本番かどうかの判別

Keelson が値 keelson で設定する KEELSON_MODE を使って、プラットフォーム上での実行を判別します。

ON_KEELSON = os.environ.get("KEELSON_MODE") == "keelson"

本番設定の不足を即時エラーにする検査は、ON_KEELSON が true の場合だけ適用してください。DEBUG をプラットフォーム判別に使うとローカルで起動できなくなるため、代用しないでください。

タイムアウト

対象	制限
HTTP リクエスト	120 秒以内にレスポンスを開始（超過で 504）。ストリーミングは開始後、無通信 120 秒・合計 300 秒まで
定期実行ジョブ（cron）	1〜600 秒（既定 300 秒。プラン上限がそれより低ければ切り詰め）
ビルド	900 秒

外部通信

アプリから外部 API やサービスへの通信はデフォルトで可能です

よくある失敗パターン

症状	原因	対処
ビルド成功、起動後すぐ落ちる	`0.0.0.0` で listen していない	`host="0.0.0.0"` を明示
ポートに接続できない	ポート番号がハードコード	環境変数 `PORT` から読み取る
モジュールが見つからない	依存マニフェストに記載がない、またはイメージのビルド時にインストールが失敗	ビルドログを確認し、依存を `requirements.txt` または `package.json` に記載する
ネイティブモジュールのビルド失敗	システムライブラリ不足	`-media` ランタイムに変更、または依存を見直す
起動コマンドが見つからない	エントリポイントのパスが間違い	ファイル名・パスを確認
事前チェックが `command_installs_dependencies` で止まる	`command` に `pip install` / `npm install` がある	削除して起動コマンドだけにする
検証が `db` 不足で止まる	`db.mode` が無い	`libsql` または `none` を宣言する
ビルドが `reserved_path_conflict` で失敗	ビルド出力の配信ルート直下に `__keelson`（予約 URL プレフィックス）がある	ディレクトリ名を変更（予約は `/__keelson/*` のみ、それ以外はアプリのもの）
定期ジョブが一度も発火しない（エラーも出ない）	スケジュールがアプリのプロセス内にある（in-process スケジューラ）。予定時刻にはアプリがゼロにスケールしている	`crons` エントリとして宣言する
UI は成功と表示されたのにメール・通知が届かない	レスポンスを返した後に回した処理が走っていない	レスポンスを返す前に済ませる。または DB のキュー表に書いて `crons` エントリでドレインし、最大 1 間隔ぶん遅れることをユーザーに伝える

失敗時の確認手順

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

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

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

判断フロー

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

必須ルール

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

仕様参照の優先順位

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

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