環境変数一覧
Keelson がアプリのコンテナに自動設定する環境変数と、ローカル開発で Keelson SDK を使うための環境変数をまとめています。
自動設定される変数は、keelson.yaml の env に書く必要はありません。自分で定義・上書きせず、Keelson が設定した値を使います。KEELSON_ で始まる名前は Keelson が管理する予約名で、env / secrets には使えません。
基本の環境変数
Section titled “基本の環境変数”| 変数 | 内容 |
|---|---|
PORT | Web アプリがリクエストを待ち受けるポート番号。起動時にこの値を読み取って使用します |
TZ | ワークスペースのタイムゾーン（例: Asia/Tokyo） |
KEELSON_MODE | Keelson 上では keelson。ローカル開発では通常は未設定。Files / Media SDK をローカル保存で使う場合や、Tasks SDK でタスクを手元で同期実行する場合は local も指定できます |
KEELSON_APP_ID | アプリの内部 ID |
KEELSON_WORKSPACE_ID | ワークスペースの内部 ID |
KEELSON_TENANT_ID | KEELSON_WORKSPACE_ID の互換用別名（値は同じ） |
KEELSON_DEPLOY_ID | 現在のデプロイの内部 ID |
KEELSON_APP_URL | アプリの公開 URL（https://<ws>--<app>.keelson.run）。絶対 URL が必要な場面で使います。Keelson がアプリの公開ホスト名を生成できる場合に設定されます |
KEELSON_DIRECTORY_BASE_URL | Identity SDK が使う Directory API のベース URL。KEELSON_APP_URL と同じ値が、同じ条件で設定されます |
既存アプリとの互換性のため、KEELSON_TENANT_ID にも KEELSON_WORKSPACE_ID と同じ値を自動設定します。旧名の廃止時期は未定です。
SDK・機能で使う環境変数
Section titled “SDK・機能で使う環境変数”Files / Media / Identity / Tasks / Email SDK 用の接続先や認証情報は、各 SDK が自動で読み取ります。通常はアプリのコードから直接参照する必要はありません。
| 変数 | 条件 | 内容 |
|---|---|---|
KEELSON_DB_URL | db.mode: libsql | Managed SQLite の接続 URL |
KEELSON_DB_AUTH_TOKEN | db.mode: libsql | Managed SQLite の認証トークン |
TURSO_DATABASE_URL / TURSO_AUTH_TOKEN | db.mode: libsql | それぞれ KEELSON_DB_URL / KEELSON_DB_AUTH_TOKEN と同じ値が設定される互換用の別名 |
KEELSON_FILES_BUCKET / KEELSON_FILES_PREFIX | コンテナ型のデプロイで、ファイル保存先が構成されているとき（通常のデプロイでは自動） | Files SDK が使う保存先 |
KEELSON_INTERNAL_MEDIA_BASE_URL / KEELSON_APP_MEDIA_TOKEN | コンテナ型のデプロイで、Media 機能が有効なとき（通常のデプロイでは自動） | Media SDK が使うアップロード先と認証トークン |
KEELSON_MEDIA_URL_PREFIX | Media SDK のアップロード先・認証トークンと同じ条件 | Media の配信 URL の先頭部分（/__keelson/media/） |
KEELSON_DIRECTORY_TOKEN | keelson apps directory enable を実行し、アプリを再デプロイした後 | Identity SDK が使う Directory API のトークン。サーバー側だけで扱います |
KEELSON_EMAIL_API_URL / KEELSON_EMAIL_TOKEN | コンテナ型のデプロイ（通常のデプロイでは自動） | Email SDK がメール送信に使う接続先と認証トークン。サーバー側だけで扱います |
KEELSON_EMAIL_WEBHOOK_SECRET | KEELSON_EMAIL_TOKEN と同じ条件 | メールの配信結果の通知の署名を検証する鍵。Email SDK の検証関数に渡します |
KEELSON_TASKS_BASE_URL | Keelson がバックグラウンドタスクを受け付けている間、Web・定期実行ジョブ・タスクの各コンテナに設定（tasks の宣言の有無は問いません） | Tasks SDK がタスクの投入と状態の取得に使う URL。自分で設定する必要はありません |
静的サイト・SPA（assets を指定し、command を省略する構成）にはコンテナがないため、実行時の環境変数は設定されません。Files / Media の SDK は静的サイトからは使えません。定期実行ジョブだけのアプリも command を省略しますが、ジョブはコンテナで動作し、SDK 用の環境変数を利用できます。
設定されないもの
Section titled “設定されないもの”NODE_ENV— 自動では設定されません。keelson.yamlのenvで"production"を宣言してください- 外部 DB の接続情報 — 自動では設定されないため、シークレットで渡します。
db.mode: noneの場合、Managed SQLite の接続情報は自動設定されません
ローカル開発で使うもの
Section titled “ローカル開発で使うもの”SDK を手元の開発環境で動かすための設定です。必要に応じてローカルの環境変数として指定し、keelson.yaml の env や Keelson のシークレットには登録しません。
| 変数 | 内容 |
|---|---|
KEELSON_MODE=local | Files / Media SDK でローカル保存を使用します。Tasks SDK では、enqueue が CLI の keelson dev task run でコマンドを手元で同期実行します。通常のローカル開発では未設定でも同じ動作になります |
KEELSON_FILES_DIR | Files SDK のローカル保存先（既定 ./.keelson/files） |
MEDIA_DIR | Media SDK のローカル保存先（既定 ./media） |
KEELSON_LOCAL_MODE=1 | Identity SDK が API に接続せず、テスト用データを返すようにします。keelson dev serve 経由で起動するときは不要です（ローカルで動かす） |
KEELSON_LOCAL_USERS_FILE | KEELSON_LOCAL_MODE=1 のときに Identity SDK が読む名簿ファイル（既定 ./.keelson/dev-users.json） |
KEELSON_LOCAL_USER_ID / KEELSON_LOCAL_USER_EMAIL / KEELSON_LOCAL_USER_NAME | ローカル開発で Identity SDK が返すテスト用ユーザーの ID・メールアドレス・表示名。名簿ファイルがあるときは使いません |
KEELSON_LOCAL_WORKSPACE_ID / KEELSON_LOCAL_WORKSPACE_ROLE / KEELSON_LOCAL_APP_ID | ローカル開発で Identity SDK が返すテスト用のワークスペース ID・ワークスペース内のロール・アプリ ID |
Identity SDK は、互換性のため旧名の KEELSON_LOCAL_TENANT_ID と KEELSON_LOCAL_TENANT_ROLE も読み取れます。新旧両方を指定した場合は、WORKSPACE を含む新しい名前の値が優先されます。旧名の廃止時期は未定です。
- 環境変数とシークレット — 自分で設定する値
- ファイルとメディア
- 認証情報をアプリで使う