keelson.yaml

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

概要

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"

databases

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

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

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

ルール:

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

crons

定期実行ジョブを定義します。Keelson 内部では Kubernetes CronJob として実行されます。

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

バックグラウンドワーカープロセスを定義します。Web アプリとは別のプロセスとして実行されます。

workers:
  - name: processor
    command: "python worker.py"
    replicas: 1

フィールド	型	必須	デフォルト	説明
`name`	string	はい	—	ワーカー名。小文字英数字とハイフン、1〜63文字
`command`	string \| list	はい	—	実行コマンド
`replicas`	int	—	`1`	レプリカ数。`0` または `1`
`resources`	object	—	`null`	リソース制約（下記参照）

replicas を 0 にすると、ワーカーの定義は保持されますが起動しません。一時的にワーカーを無効化したい場合に使用します。

ルール:

現在のバージョンでは最大 1 つまで定義可能
トップレベルの command が設定されている場合のみ使用可
type: web との併用不可

resources

ワーカーの CPU・メモリの制約を指定できます。

workers:
  - name: processor
    command: "python worker.py"
    resources:
      requests:
        cpu: "200m"
        memory: "256Mi"
      limits:
        cpu: "1"
        memory: "512Mi"

requests と limits のいずれかに、cpu または memory を1つ以上指定してください。

storage

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

storage を省略した場合、/data は一時領域となり、Pod の再起動時にデータが失われます。データを永続化するには storage を設定してください。

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 の組み合わせにより、デプロイモードが自動的に決まります。

モード	`command`	`assets`	`fallback`	説明
コンテナ	あり	なし	—	通常のアプリデプロイ
静的サイト	なし	あり	なし	静的ファイルのみ
SPA	なし	あり	あり	SPA（フォールバック付き）
ハイブリッド	あり	あり	必須	静的ファイル + バックエンド 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 + バックグラウンドワーカー

slug: task-worker
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/tasks.db"

storage:
  disk_id: task-worker-data

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

workers:
  - name: default
    command: "python -m pip install --user -r requirements.txt && python worker.py"
    replicas: 1

ハイブリッド（静的ファイル + バックエンド 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` を使っている	データは永続化されず Pod 再起動時に失われます