keelson.yaml の設定

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

keelson.yaml は、Keelson がアプリをどのようにビルドし、起動し、公開するかを判断するための設定ファイルです。

このページでは、keelson.yaml が何のためにあるのか、何を書けばよいのか、どう使われるのかを説明します。各フィールドの完全な定義については keelson.yaml リファレンスを参照してください。

ただし、keelson.yaml は Keelson の Agent Skill 機能を使えば AI エージェントが自動生成してくれるため、通常は自分で作成する必要はありません。

keelson.yaml とは

keelson.yaml は、アプリごとに用意する設定ファイルです。プロジェクトのルートディレクトリに配置します。

Keelson はこのファイルを読み取り、次のことを判断します。

アプリの識別子（URL の一部になる）
どのランタイムで動かすか
どのように起動するか
永続ストレージやデータベースを使うか
定期実行ジョブやバックグラウンドワーカーがあるか
静的アセット配信を行うか

keelson.yaml は、アプリのコードそのものではなく、そのアプリを Keelson 上で動かすための説明書です。すべての設定項目を覚える必要はなく、まずは最小限の構成から始められます。

なぜ必要か

同じ Web アプリでも、使用する言語、起動コマンド、必要な機能はアプリごとに異なります。

Keelson は keelson.yaml を通じてその違いを理解し、適切な方法でアプリをデプロイします。このファイルがないと、Keelson はそのアプリをどう扱えばよいか判断できません。

AI エージェントでデプロイする場合も、keelson.yaml はアプリの構成を理解するための重要な手がかりになります。エージェントがアプリのコードを読み取って keelson.yaml を自動生成することもできます。

デプロイ時にどう使われるか

keelson.yaml は、デプロイの開始時に読み取られます。

Keelson はこの設定をもとに、次の処理を行います。

設定の検証 — フィールドの値やフィールド間の制約をチェックする
ビルド — ランタイムに応じたコンテナイメージを作成する
起動 — command で指定されたコマンドでアプリを開始する
機能の有効化 — ストレージ、データベース、定期実行ジョブなど、設定された機能を準備する
公開 — slug に基づいた URL でアプリにアクセスできるようにする

設定がアプリの実際の構成と合っていない場合、ビルドに失敗したり、ビルドは成功しても起動できなかったりすることがあります。

主要なフィールド

keelson.yaml のフィールドはすべてトップレベルに配置します。

必須フィールド

フィールド	説明	例
`slug`	アプリの識別子。URL の一部になる	`my-app`
`runtime`	実行環境	`python-slim`, `node-slim`, `go-slim`
`command`	起動コマンド	`"python app.py"`

command は、依存パッケージのインストールと起動を 1 つのコマンドにまとめて書きます。

command: "python -m pip install -r requirements.txt && python app.py"

よく使うフィールド

フィールド	説明
`env`	環境変数（キーと値のペア）
`storage`	永続ストレージの設定
`databases`	SQLite データベースの設定
`crons`	定期実行ジョブ
`workers`	バックグラウンドワーカー
`assets`	静的アセット配信
`type`	アプリ種別（`web` を指定すると静的サイトモード）

各フィールドの型、制約、指定可能な値については keelson.yaml リファレンスを参照してください。

デプロイモード

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

パターン	`command`	`assets`	動作
通常のアプリ	あり	なし	コンテナとして起動
静的サイト / SPA	なし	あり	静的ファイルを配信
ハイブリッド	あり	あり	静的ファイル + バックエンド API

keelson.yaml に書かないこと

API キー、トークン、パスワードなどの秘密情報は keelson.yaml に直接書かないでください。

keelson.yaml はソースコードと一緒にリポジトリに含まれるファイルです。秘密情報は環境変数またはシークレットとして、コンソールから設定します。

# NG: 秘密情報を直接書いている
env:
  OPENAI_API_KEY: "sk-xxxxxxxxxxxxx"

# OK: 値はコンソールで設定し、keelson.yaml には書かない
env:
  PORT: "8080"
  NODE_ENV: "production"

環境変数の管理については環境変数とシークレットを参照してください。

最小構成から始める

まずは slug、runtime、command の 3 つだけで始められます。

Python

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

Node.js

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

Go

slug: my-app
runtime: go-slim
# Keelson が deploy 時に Linux 向け binary を `./app` としてビルドします。
command: "./app"
env:
  PORT: "8080"

ランタイムには -slim（軽量）と -media（画像・動画処理ライブラリ含む）の 2 種類があります。迷った場合は -slim から始めてください。

アプリの種類ごとの構成

アプリの種類によって、使うフィールドが変わります。

Web アプリ + SQLite

データベースを使うアプリでは、storage と databases を追加します。

slug: my-app
runtime: python-slim
command: "python -m pip install -r requirements.txt && python app.py"
env:
  PORT: "8080"
  DB_PATH: "/data/main.db"

storage:
  disk_id: my-app-data

databases:
  - name: main
    type: sqlite
    path: /data/main.db

storage を設定しないと、データは永続化されず Pod の再起動時に失われます。

静的サイト / SPA

type: web を指定し、assets でアセットディレクトリを設定します。

slug: my-site
type: web
runtime: node-slim

assets:
  dir: dist
  fallback: index.html

定期実行ジョブ

Web サーバーなしで、定期的にスクリプトを実行するだけのアプリです。

slug: daily-report
runtime: python-slim

crons:
  - name: generate
    schedule: "0 9 * * *"
    command: "python report.py"
    timeout: 120

ハイブリッド（静的ファイル + API）

フロントエンドの静的ファイルとバックエンド API を 1 つのアプリで提供します。

slug: my-app
runtime: node-slim
command: "npm install && node server.js"
env:
  PORT: "8080"

assets:
  dir: public
  fallback: index.html
  api: /api

各構成パターンの完全な例は keelson.yaml リファレンスを参照してください。