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	—	`{}`	永続ストレージの設定
`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

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

YAML の自動型変換を避けるため、値はすべて引用符で囲むことを推奨します。

env:
  PORT: "8080"
  NODE_ENV: "production"
  DEBUG: "false"
  DB_PATH: "/data/main.db"

db

データベースの実行モードを選択します。libSQL クライアントを使える新規アプリでは mode: turso（Keelson Managed SQLite）を推奨します。

db:
  mode: turso   # turso | litestream | none

フィールド	型	必須	デフォルト	説明
`mode`	string	—	`none`	`turso` / `litestream` / `none` のいずれか

`mode`	意味	ティア
`turso`	Keelson Managed SQLite（推奨）。アプリごとに専用のマネージド libSQL DB を自動プロビジョニングし、テナント / アプリ単位で分離。接続情報（`TURSO_DATABASE_URL` / `TURSO_AUTH_TOKEN`）が環境変数で注入される。scale-to-zero 可	標準
`litestream`	`/data` 上の SQLite ファイルを Litestream で継続レプリケーション（レガシー互換）。常時ウォームで動作	常駐ティア
`none`	Keelson は DB を管理しない（既定）。DB 不要、または外部 DB を直接利用する場合	標準

ルール:

db を省略した場合、mode は none として扱われます（既存の keelson.yaml は従来どおり動作）
Managed SQLite を使うには mode: turso を明示指定してください

databases

SQLite データベースの設定です。databases で宣言したファイルは、storage で定義された永続ストレージ上に配置されます。storage を省略した場合、データは永続化されずアプリの再起動時に失われます。データを保持したい場合は storage も合わせて設定してください。

新規アプリでは、テナント単位で分離される Keelson Managed SQLite の利用を推奨します。/data 上の SQLite ファイルを直接使う構成はレガシー互換モード（常駐ティア）です。

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

フィールド	型	必須	デフォルト	説明
`name`	string	—	`db-{index}`	データベースの識別名
`type`	string	はい	—	`sqlite` のみ対応
`path`	string	はい	—	ファイルのマウントパス

ルール:

path は /data/ で始まる必要があります
name と path はそれぞれ重複不可

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 な状態は Managed SQLite（db.mode: turso）またはオブジェクトストレージに置いてください（ワーカーが /data に書いたファイルは破棄されます）。

db:
  mode: turso

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 との併用不可
db.mode: litestream とは併用不可（Job が litestream の SQLite を共有できないため）
replicas / resources は指定できません（CPU / メモリはアプリ単位で設定され、ワーカーに replica 数の概念はありません）

storage

永続ストレージの設定です。コンテナ内の /data にマウントされます。databases で定義する SQLite ファイルもこの領域を使用します。

storage を省略した場合、/data は一時領域となり、再起動時にデータが失われます。データを永続化するには storage を設定してください（/data はオブジェクトストレージへ自動同期されます）。

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"
env:
  PORT: "8080"
  PYTHONUNBUFFERED: "1"
  PYTHONUSERBASE: "/deps/.local"
  DB_PATH: "/data/customers.db"

storage:
  disk_id: flask-crud-data

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

静的サイト（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 行を Managed SQLite に書き、ワーカーが every 間隔で溜まった行を処理します。ワーカーは Web と別コンテナで走るため、共有状態は db.mode: turso に置きます。

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

db:
  mode: turso

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"

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

storage:
  disk_id: photo-data

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

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"
env:
  PORT: "8080"
  NODE_ENV: "production"
  DB_PATH: "/data/notes.db"

storage:
  disk_id: node-crud-data

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

よくあるエラー

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