keelson.yaml

概要

keelson.yaml は、プロジェクトルートに配置するデプロイ設定ファイルです。アプリのランタイム、起動コマンド、環境変数、データベース、定期実行ジョブなどを定義します。

デプロイ時に Keelson はこのファイルを読み取り、その内容に基づいてビルドと実行環境を決定します。

最小構成の例

slug: my-app
runtime: python-slim
command: "python app.py"
env:
  PORT: "8080"

トップレベルフィールド

フィールド	型	必須	デフォルト	説明
`slug`	string	はい	—	アプリの識別子（URLの一部になります）
`type`	string	—	`null`	アプリ種別。`"web"` のみ指定可。指定時は `crons`・`workers` 不可
`runtime`	string	はい	—	実行環境。対応ランタイムを参照
`command`	string \| list	条件付き	—	起動時に実行するコマンド。`crons` がない場合は必須
`env`	map	—	`{}`	環境変数
`databases`	list	—	`[]`	SQLite データベースの設定
`crons`	list	条件付き	`[]`	定期実行ジョブ。`command` がない場合は必須
`workers`	list	—	`[]`	バックグラウンドワーカー
`storage`	object	—	`{}`	非推奨の `disk_id` のみを受理する互換ブロック。一般ファイルの永続化は設定しない
`assets`	object	—	`null`	静的アセット配信の設定

slug

アプリの識別子です。公開URLの一部として使われます（例: my-app.keelson.run）。

slug: my-app

ルール:

使用できる文字: 小文字英数字とハイフン（a-z, 0-9, -）
長さ: 1〜63文字
--（連続ハイフン）は使用不可
予約語: api, console, www, admin（これが現時点での完全な一覧です）

type

アプリ種別を指定します。省略可能です。

type: web

指定できる値は "web" のみです。type: web を指定すると、静的アセット配信（assets）が有効になり、command なしでのデプロイが可能になります。

制約:

type: web を指定した場合、crons および workers は使用できません

runtime

アプリの実行環境を指定します。静的サイトのみのデプロイでも必須です。

対応ランタイム

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

迷った場合は -slim から始めてください。メディア処理系のライブラリが必要になった場合に -media へ切り替えます。

command

起動時に実行するコマンドです。依存パッケージのインストールなどの準備処理を含めることもできます。文字列またはリスト形式で指定できます。

# 文字列形式（シェル経由で実行）
command: "python -m pip install -r requirements.txt && python app.py"

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

ルール:

command と crons のどちらかは必須です（両方指定も可）
type: web で assets のみのデプロイでは省略可

env

環境変数をキーと値のペアで定義します。値はすべて文字列として扱われます。

値は必ず引用符で囲んでください。 引用符の無い値は env_value_not_string で拒否され、デプロイは開始されません。数値・真偽値も同様に引用符が必要です（NODE_ENV: production / RETRIES: 3 / DEBUG: true はいずれも拒否）。

env:
  PORT: "8080"
  NODE_ENV: "production"
  DEBUG: "false"
  LOG_LEVEL: "info"

引用符が必須なのは、keelson.yaml を CLI（YAML 1.2）と API（YAML 1.1）の 2 つの実装が解析しており、引用符の無いスカラーの型解決が食い違うためです。たとえば K: 0o123 は経路によって "83" にも "0o123" にもなり、どちらもエラーを出さないまま別の値がデプロイされていました。引用符で囲めばどちらの実装でも同じ文字列になります。

key の制約

引用符を付けない key は、英字かアンダースコアで始まり、英数字とアンダースコアだけで構成される必要があります（NODE_ENV、DB_POOL など通常の環境変数名はそのまま書けます）。加えて、次の語は引用符なしでは使えません:

yes Yes YES no No NO true True TRUE false False FALSE on On ON off Off OFF null Null NULL

これらは YAML 1.1 で真偽値・null として解釈されるため、引用符が無いと 2 つの実装で 環境変数の名前や個数が変わってしまいます。

引用符を付ければ任意の key が使えます。

env:
  NODE_ENV: "production"   # そのまま書ける
  "MY-VAR": "x"            # ハイフン入りは引用符が必要
  "yes": "x"               # 予約語は引用符が必要

また、env を YAML の merge key（<<）で組み立てることはできません。 env の重複宣言、および env 内での同じ key の重複も拒否されます。

db

アプリのデータベースの扱いを選択します。新規アプリでは mode: libsql（自動で用意されるデータベース・設定不要）を推奨します。

db:
  mode: libsql   # libsql | none。レガシー別名 `turso` は `libsql` に正規化されます

フィールド	型	必須	デフォルト	説明
`mode`	string	—	`none`	`libsql` / `none` のいずれか（`turso` は `libsql` の別名）

`mode`	意味	ティア
`libsql`	自動で用意されるデータベース（推奨）。アプリごとに専用のデータベースを自動プロビジョニングし、テナント / アプリ単位で分離。接続情報（`KEELSON_DB_URL` / `KEELSON_DB_AUTH_TOKEN`）が環境変数で注入される。契約・接続設定は不要・無料枠内。scale-to-zero 可	標準
`none`	Keelson は DB を管理しない（既定）。DB 不要、または外部 DB を直接持ち込む場合	標準

ルール:

db を省略した場合、mode は none として扱われます（既存の keelson.yaml は従来どおり動作）
自動で用意されるデータベースを使うには mode: libsql を明示指定してください
/data 上のファイル SQLite を永続化する経路は提供しません（ファイル DB は永続化されません）

外部データベースを使う場合（mode: none）: 自動で用意されるデータベースは設定不要・無料枠内で使えますが、Postgres・MySQL・外部の libSQL などを使いたい場合は mode: none を指定し、接続情報を secrets として自分で設定します（プラットフォームは外部 DB の接続情報を注入しません）。ファイル SQLite を前提とするフレームワーク（Django 等）は、この外部データベース経路で持ち込んでください。

crons

定期実行ジョブを定義します。Keelson がスケジュールに従ってジョブを起動・実行します。

crons:
  - name: cleanup
    schedule: "0 3 * * *"
    command: "python cleanup.py"
    timeout: 60

フィールド	型	必須	デフォルト	説明
`name`	string	はい	—	ジョブ名。小文字英数字とハイフン、1〜63文字
`schedule`	string	はい	—	cron 式（5フィールド形式）
`command`	string \| list	はい	—	実行コマンド
`timeout`	int	—	`300`	タイムアウト（秒）。1〜3600

ルール:

最大 10 個まで定義可能
name の重複不可
type: web との併用不可

cron 式の例

式	意味
`* * * * *`	毎分
`0 * * * *`	毎時 0 分
`0 3 * * *`	毎日 3:00
`0 0 * * 1`	毎週月曜 0:00

workers

バックグラウンドワーカーを定義します。ワーカーは**常駐プロセスではなく「定期ドレイン」**です。プラットフォームが every 間隔ごとにワーカーを起こし、command を 1 回実行し、溜まった仕事を処理して exit すると止まります。tick と tick の間はプロセスが存在しません。

ワーカーは Web アプリとは別のコンテナで実行されるため、/data を共有しません。durable な状態はデータベース（db.mode: libsql）またはオブジェクトストレージに置いてください（ワーカーが /data に書いたファイルは破棄されます）。

db:
  mode: libsql

workers:
  - name: drain
    command: "python worker.py"
    every: 10m
    timeout: 2m

フィールド	型	必須	デフォルト	説明
`name`	string	はい	—	ワーカー名。小文字英数字とハイフン、1〜63文字
`command`	string \| list	はい	—	実行コマンド。溜まった仕事を処理して exit 0 する drain 型で書く
`every`	string	—	`30m`	tick 間隔。許容値は下記
`timeout`	string	—	`5m`（duty 上限で切り下げ）	1 tick の kill 期限。duty 規則で上限が決まる

every（tick 間隔）の許容値:

分値: 5m / 10m / 15m / 20m / 30m / 60m（60 を割り切る値）
時間値: 2h / 3h / 4h / 6h / 8h / 12h / 24h（24 を割り切る値）

timeout と duty 規則: timeout ≤ every × 1/5（duty cycle 20% 以下）。例: every: 30m なら timeout は最大 6m。既定は 5m で、短い every では上限まで自動的に切り下げられます。

ルール:

ワーカーの本数はプランによって異なります（下記「プラン制限」参照）
トップレベルの command が設定されている場合のみ使用可
type: web との併用不可
replicas / resources は指定できません（CPU / メモリはアプリ単位で設定され、ワーカーに replica 数の概念はありません）

storage

storage は非推奨の disk_id だけを受理します。値は無視され、永続ストレージや /data の自動同期を有効にしません。

一般ファイルの永続 I/O は keelson.yaml では設定できません。オブジェクトストレージへ直接読み書きするデータファイル SDK を後続タスクで提供予定です。

storage:
  disk_id: my-disk

フィールド	型	必須	デフォルト	説明
`disk_id`	string	—	`null`	非推奨・無視される旧ストレージ識別子。小文字英数字とハイフン、1〜32文字

assets

静的アセット配信の設定です。静的サイトや SPA のデプロイ、バックエンド API とのハイブリッド構成に使用します。

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

フィールド	型	必須	デフォルト	説明
`dir`	string	はい	—	アセットディレクトリ（プロジェクトルートからの相対パス）
`fallback`	string	—	`null`	SPA 用フォールバックファイル（例: `index.html`）
`api`	string	—	`null`	バックエンド API のパスプレフィックス（例: `/api`）

api を指定すると、そのパス配下のリクエストはバックエンドアプリへ転送され、それ以外は静的アセットとして配信されます。

ルール:

dir に .. を含むパスは使用不可
api は / で始まる必要があります
api に /__keelson 配下のパスは使用不可
api はトップレベルの command が設定されている場合のみ使用可
ハイブリッド構成（assets + command）では fallback が必須

デプロイモード

デプロイモードは選択するものではなく、command と assets という持ち物から自動的に決まる導出値です。CLI / API の出力（keelson status --json など）は deploy_mode の生ラベルをそのまま返すため、対応表で読み替えてください。

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

バリデーションルール

設定の組み合わせには以下の制約があります。

ルール	説明
`command` または `crons` が必須	少なくとも一方を指定してください（`type: web` の静的サイトデプロイを除く）
`type: web` の排他制約	`crons` および `workers` とは併用できません
`workers` には `command` が必要	トップレベルの `command` がない場合、`workers` は使用できません
`assets.api` には `command` が必要	API プレフィックスはバックエンドがある場合のみ指定できます
ハイブリッドには `fallback` が必要	`assets` と `command` を両方指定する場合、`fallback` は必須です

構成例

Web アプリ + SQLite（最も一般的）

slug: flask-crud
runtime: python-slim
command: "python -m pip install --user -r requirements.txt && python app.py"
db:
  mode: libsql
env:
  PORT: "8080"
  PYTHONUNBUFFERED: "1"
  PYTHONUSERBASE: "/deps/.local"

静的サイト（SPA）

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

assets:
  dir: dist
  fallback: index.html

定期実行ジョブのみ（Web なし）

slug: cron-logger
runtime: python-slim
env:
  PYTHONUNBUFFERED: "1"

crons:
  - name: heartbeat
    schedule: "* * * * *"
    command: "python heartbeat.py"
    timeout: 30

Web + バックグラウンドワーカー（定期ドレイン）

Web アプリが pending 行をデータベースに書き、ワーカーが every 間隔で溜まった行を処理します。ワーカーは Web と別コンテナで走るため、共有状態は db.mode: libsql に置きます。

slug: task-worker
runtime: python-slim
command: "python app.py"
env:
  PYTHONUNBUFFERED: "1"

db:
  mode: libsql

workers:
  - name: drain
    command: "python worker.py"
    every: 10m
    timeout: 2m

ハイブリッド（静的ファイル + バックエンド API）

slug: photo-galleries
runtime: python-slim
command: "python -m pip install --user -r requirements.txt && python app.py"
env:
  PORT: "8080"
  PYTHONUNBUFFERED: "1"
  PYTHONUSERBASE: "/deps/.local"

db:
  mode: libsql

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

Go アプリ（最小構成）

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

Node.js アプリ

slug: node-crud
runtime: node-slim
command: "npm install && npm start"
db:
  mode: libsql
env:
  PORT: "8080"
  NODE_ENV: "production"

よくあるエラー

エラー原因	説明
`path` が `/data/` で始まっていない	`databases.path` は `/data/` 配下である必要があります
`api` が `/` で始まっていない	`assets.api` は `/` で始まる必要があります
`command` も `crons` もない	少なくとも一方を指定してください（`type: web` の静的デプロイを除く）
`workers` があるのに `command` がない	`workers` はトップレベルの `command` が必要です
`env` の値が引用符で囲まれていない	`true`/`false`/数値は YAML に型変換されます。すべて引用符で囲んでください