ビルドとランタイム

TODO（内部向け・リリース前に対応して削除）

リリースまでに対応必須

• SPA + 静的サイトの説明を入れる必要あり
• タイムアウトの設定値を確定して反映

ビルドと実行の流れ

Keelson にアプリをデプロイすると、以下の流れで公開されます。

ソースコード → CLI / AI エージェントが送信 → Keelson がビルド → コンテナとして起動 → 公開 URL 発行
                                                                        ↓
                                                          認証・アクセス制御が前段で適用

1. ソースコードを送る — CLI（keelson deploy）または AI エージェントの Skill がソースコードと keelson.yaml を Keelson に送信します
2. Keelson がビルドする — 指定されたランタイムに基づいて、依存関係のインストールと実行環境の構築が自動で行われます
3. コンテナとして起動する — ビルドされたアプリが keelson.yaml の command に従って起動します
4. 公開 URL が発行される — https://<slug>.keelson.run/ の URL が払い出されます
5. 認証・アクセス制御が適用される — すべてのリクエストは認証プロキシを経由し、ログイン済みの許可されたメンバーだけがアクセスできます

開発者がビルドやインフラの設定を行う必要はありません。keelson.yaml に必要な情報を記述すれば、あとは Keelson が処理します。

---

Keelson の実行モデル

Keelson では、1つのアプリが1つの実行単位になります。アプリの種類に応じて、以下の形態で動作します。

Web アプリ（常駐型）

HTTP サーバーとして起動し、リクエストを受け付け続けます。ブラウザからアクセスする UI や、JSON API を返すバックエンドがこの形態です。

定期実行ジョブ（cron）

スケジュールに従って定期的にコマンドを実行します。集計処理、通知送信、データ同期などに使います。Web アプリとは独立して定義でき、Web アプリを持たない cron だけの構成も可能です。

ワーカープロセス

Web アプリと並行して動くバックグラウンド処理です。キュー処理やデータの非同期処理に使います。Web アプリが存在する場合にのみ追加できます。

組み合わせ

これらは組み合わせて使えます。

構成	説明
Web アプリのみ	もっとも一般的な構成
Web アプリ + cron	アプリに加えて定期処理を実行
Web アプリ + ワーカー	アプリに加えてバックグラウンド処理を実行
cron のみ	UI なしで定期実行だけを行う

アプリの状態

アプリには3つの状態があります。

• running — 実行中。Active Apps 枠を消費
• sleep — 自動スリープ。アクセス時に自動起動
• stop — 手動停止。ダッシュボードから手動で起動

再デプロイすると、新しいコードでアプリが置き換えられます。/data に保存されたデータは再デプロイ後も保持されます。

---

対応している言語・ランタイム

現時点で以下のランタイムに対応しています。

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

keelson.yaml の runtime フィールドで指定します。

runtime: python-slim

自分のアプリがデプロイできるか確認する

対応ランタイムや制約の詳細は Keelson Deploy Spec にまとまっています。Claude Code、Codex、ChatGPT などの AI エージェントに以下の URL を渡せば、自分のアプリが Keelson にデプロイできるかチェックしてもらえます。

https://keelson.dev/ja/docs/reference/deploy-spec.txt

依存関係のインストール

依存関係は 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"

---

起動方法

起動コマンド

keelson.yaml の command で起動コマンドを指定します。

# 文字列形式（/bin/sh -c で実行）
command: "python app.py"

# リスト形式（exec で直接実行）
command:
  - python
  - app.py

ポートの扱い

Web アプリは環境変数 PORT で指定されたポートで HTTP リクエストを待ち受けてください。keelson.yaml の env で設定します。

env:
  PORT: "8080"

アプリ側のコード例:

import os
port = int(os.environ.get("PORT", 8080))

const port = process.env.PORT || 8080;

待ち受けアドレス

HTTP サーバーは必ず 0.0.0.0 で listen してください。127.0.0.1 や localhost ではリクエストが届きません。

uvicorn.run(app, host="0.0.0.0", port=port)

app.listen(port, "0.0.0.0");

---

ビルド時と実行時の違い

Keelson のデプロイには2つのフェーズがあります。

	ビルド時	実行時
何が起きるか	ソースコードの取得、依存関係のインストール、実行環境の構築	アプリの起動、リクエストの処理
環境変数	keelson.yaml の env で定義した値が利用可能	同じ env の値に加え、Keelson が設定するシステム環境変数が利用可能
ネットワーク	外部パッケージレジストリ（npm, PyPI など）への通信が可能	外部 API への通信が可能
データ永続化	/data はまだ利用できない	/data に書き込んだデータは永続化される

ログ

• ビルドログ — 依存関係のインストールやビルド処理の出力。ビルドが失敗した場合の原因特定に使います
• 実行ログ — アプリの標準出力・標準エラー出力。実行中のエラーやリクエスト処理の確認に使います

いずれもダッシュボードから確認できます。

---

制限事項

リソース

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

実行環境

• root 権限は使えません — アプリは非 root ユーザーとして実行されます
• systemd やデーモン管理は使えません — プロセス管理は command で起動した単一プロセスが基本です
• コンテナ外への永続書き込みはできません — データを永続化するには /data ディレクトリを使ってください。それ以外のパスへの書き込みは再デプロイ時に失われます

タイムアウト

• HTTP リクエストには一般的なタイムアウトが適用されます
• 定期実行ジョブ（cron）の timeout は 1〜3,600 秒で設定可能です（デフォルト: 300 秒）

外部通信

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

---

よくある失敗

0.0.0.0 で listen していない

多くのフレームワークはデフォルトで 127.0.0.1（localhost）で listen します。Keelson ではリクエストがコンテナ外から届くため、0.0.0.0 を明示する必要があります。

# NG
uvicorn.run(app, host="127.0.0.1", port=port)

# OK
uvicorn.run(app, host="0.0.0.0", port=port)

ポートがハードコードされている

ポート番号をコードに直接書くと、Keelson の環境で一致しない場合があります。環境変数 PORT から読み取ってください。

// NG
app.listen(3000);

// OK
app.listen(process.env.PORT || 8080);

依存関係がインストールされていない

command に依存関係のインストールを含め忘れると、実行時にモジュールが見つからずエラーになります。

# NG
command: "python app.py"

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

起動コマンドが間違っている

エントリポイントのファイル名やパスが間違っていると、アプリが起動しません。ローカルで同じコマンドを実行して動作を確認してください。

ローカルでは動くが Keelson では落ちる

よくある原因:

• ローカルにだけ存在するファイルやディレクトリに依存している
• 環境変数が設定されていない
• localhost 前提の外部サービス接続（ローカル DB など）

失敗時の確認手順

1. ビルドログを確認する — ダッシュボードでビルドの出力を確認し、依存関係のインストールが成功しているか確認
2. 実行ログを確認する — アプリの起動時エラーやランタイムエラーがないか確認
3. keelson.yaml を確認する — runtime、command、env の設定が正しいか見直す

---

サンプル: Node / Python の最小構成

Python（FastAPI）

必要ファイル:

my-api/
├── keelson.yaml
├── requirements.txt
└── app.py

keelson.yaml:

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

requirements.txt:

fastapi
uvicorn

app.py:

from fastapi import FastAPI
import uvicorn, os

app = FastAPI()

@app.get("/")
def index():
    return {"message": "Hello from Keelson"}

if __name__ == "__main__":
    port = int(os.environ.get("PORT", 8080))
    uvicorn.run(app, host="0.0.0.0", port=port)

Node.js（Express）

必要ファイル:

my-app/
├── keelson.yaml
├── package.json
└── index.js

keelson.yaml:

slug: my-app
runtime: node-slim
command: "npm install && npm start"
env:
  PORT: "8080"
  NODE_ENV: production

package.json:

{
  "name": "my-app",
  "scripts": { "start": "node index.js" },
  "dependencies": { "express": "^4" }
}

index.js:

const express = require("express");
const app = express();
const port = process.env.PORT || 8080;

app.get("/", (req, res) => {
  res.json({ message: "Hello from Keelson" });
});

app.listen(port, "0.0.0.0", () => {
  console.log(`Listening on port ${port}`);
});

デプロイ後の動作確認

デプロイが完了すると https://my-app.keelson.run/ のような URL が発行されます。ブラウザでアクセスし、{"message": "Hello from Keelson"} が表示されれば成功です。

---

AI に依頼するときのプロンプト例

Keelson は AI で生成したアプリをそのままデプロイできるように設計されています。以下のようなプロンプトを AI に渡すと、Keelson 互換のアプリを生成しやすくなります。

基本的な指示

Keelson で動く FastAPI アプリを作ってください。環境変数 PORT で指定されたポートで 0.0.0.0 を listen してください。

データ永続化を使う場合

SQLite データベースを /data/main.db に保存してください。/data は永続化されるディレクトリです。

定期実行を含む場合

毎日午前3時にデータを集計するバッチ処理を追加してください。メインの Web アプリとは別に cron ジョブとして実行します。

keelson.yaml の生成を依頼する場合

このアプリ用の keelson.yaml を作成してください。ランタイムは python-slim、起動コマンドは pip install --user -r requirements.txt && python app.py です。

ポイント

AI にアプリを生成させるとき、以下の3点を伝えるとスムーズです。

1. ポート — PORT 環境変数から読み取り、0.0.0.0 で listen する
2. データ保存先 — ファイルや SQLite は /data ディレクトリに置く
3. 起動方法 — 単一のコマンドで起動できるようにする

---

Keelson のビルド・ランタイムが向いているケース

• 標準的な Node.js / Python / Go アプリ — 特殊なビルドツールチェーンが不要
• AI で生成したアプリをすぐに動かしたい — Dockerfile を書かずにデプロイできる
• 依存関係が pip / npm / go mod で管理されている — command 内でインストールするだけ
• HTTP サーバーとして起動するアプリ — ポートを listen するだけで公開される

向いていないケース

• Dockerfile による細かいビルド制御が必要 — Keelson は独自の Dockerfile を使えません
• システムパッケージの追加インストールが必要 — apt-get 等で追加するパッケージが多い場合は media ランタイムで対応できるか確認してください
• root 権限やデーモンプロセスが前提 — アプリは非 root で動作し、systemd は使えません
• ビルド成果物を細かくキャッシュしたい — ビルドキャッシュの制御は Keelson に委ねる形です

---

よくある質問

Dockerfile は使えますか？

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

ビルドにかかる時間はどのくらいですか？

依存関係の量によりますが、一般的な小〜中規模のアプリであれば1〜2分程度です。

外部の API やサービスに接続できますか？

はい。アプリから外部への通信（Egress）はデフォルトで可能です。Business プラン以上では通信先をホスト名単位で制限することもできます。

ビルドが失敗したらどうすればいいですか？

ダッシュボードでビルドログを確認してください。AI エージェントにログを渡して「このビルドエラーを修正して」と依頼するのも有効です。