Title: Keelson Deploy Spec
Spec-Version: 2025-03-14
Last-Updated: 2025-03-14
Canonical-URL: https://keelson.dev/ja/docs/reference/deploy-spec/
Raw-URL: https://keelson.dev/ja/docs/reference/deploy-spec.txt
Language: ja

---

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

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

クイックスタートや操作手順は [デプロイする](/ja/docs/deploy/deploy/) を参照してください。

---

## デプロイ成功の定義

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

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

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

---

## 必須ファイル

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

最小構成:

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

各フィールドの詳細は [keelson.yaml リファレンス](/ja/docs/reference/keelson-yaml-reference/) を参照してください。

---

## 対応ランタイム

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` を設定してください
- 詳細は [永続ストレージ](/ja/docs/building-apps/persistent-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` 内でインストールします。

```yaml
# 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 キーやトークンなど、コードに含めたくない値

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

詳細は [環境変数とシークレット](/ja/docs/deploy/environment-variables/) を参照してください。

### 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` を追加 |
| 起動コマンドが見つからない | エントリポイントのパスが間違い | ファイル名・パスを確認 |

### 失敗時の確認手順

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

---

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

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

### 判断フロー

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

### 必須ルール

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

### 仕様参照の優先順位

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

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

---

## 関連資料

- デプロイする: https://keelson.dev/ja/docs/deploy/deploy/
  デプロイの手順と流れ
- 環境変数とシークレット: https://keelson.dev/ja/docs/deploy/environment-variables/
  API キーや設定値の管理方法
- アプリ URL: https://keelson.dev/ja/docs/deploy/public-url/
  デプロイ後に発行される URL の仕様
- keelson.yaml リファレンス: https://keelson.dev/ja/docs/reference/keelson-yaml-reference/
  設定ファイルの全フィールド定義
- ビルドとランタイム: https://keelson.dev/ja/docs/building-apps/build-and-runtime/
  ビルドプロセスと実行環境の詳細
- 永続ストレージ: https://keelson.dev/ja/docs/building-apps/persistent-storage/
  /data ディレクトリとデータ永続化