フレームワーク別の注意点

このページでは、フレームワークごとの本番向けの起動方法と注意点を説明します。Web サーバーは、環境変数 PORT で指定されたポートで起動してください。データベースや通信方式に制約があるフレームワークもあるため、対応アプリと制約も確認してください。

開発サーバーは、性能やエラー画面での内部情報の表示、終了時のリクエスト処理などに問題があるため、本番向けのサーバーを使用してください。

通常の設定は AI エージェントに任せられます。このページは、起動方法を確認したいときや、デプロイ時の問題を調べるときに、自分のフレームワークの箇所を参照してください。

サーバー側のアプリに共通する設定

0.0.0.0 と環境変数 PORT で指定されたポートで待ち受ける。 127.0.0.1 ではリクエストが届きません
起動コマンドにインストール処理を含めない。 依存パッケージは requirements.txt / pyproject.toml / package.json / go.mod などをもとに、ビルド時にインストールされます
停止は SIGTERM → 10 秒後に SIGKILL。 処理中のリクエストは 10 秒以内に終わらせます
worker 数はまず 1 にします。 増やす場合は、利用できる CPU・メモリとアプリの処理内容に合わせて調整します
デバッグモードは既定で無効にします。 デバッグ画面は環境変数（DB の認証トークンを含む）を表示することがあります
「Keelson 上か」の判別は KEELSON_MODE。 値が keelson ならプラットフォーム上です。実行環境の判定と、デバッグモードの有効・無効は分けて扱います

import os

ON_KEELSON = os.environ.get("KEELSON_MODE") == "keelson"
DEBUG = os.environ.get("DEBUG", "false").lower() == "true"   # 既定は false

Python

FastAPI / uvicorn

command: "uvicorn main:app --host 0.0.0.0 --port $PORT"
env:
  PYTHONUNBUFFERED: "1"

--reload は付けません（ファイル監視がメモリを消費し、二重起動することがあります）。worker は既定の 1 のままにします。

Flask

app.run() は開発サーバーです。gunicorn を requirements.txt に追加して起動します。

command: "gunicorn --bind 0.0.0.0:$PORT --workers 1 --threads 8 --timeout 0 --graceful-timeout 9 app:app"
env:
  PYTHONUNBUFFERED: "1"

app:app はモジュール名とアプリオブジェクト名に置き換えます。--graceful-timeout 9 で 10 秒の SIGTERM 猶予に収めます。

Django

Django は、外部 DB（PostgreSQL など）に接続する構成でのみデプロイできます。Managed SQLite（libSQL）には Django ORM 用のバックエンドがないため、Managed SQLite やファイル SQLite を DB にする構成は未対応です。

db.mode: none にし、接続情報はシークレットで渡します。起動は runserver ではなく gunicorn を使います。

command: "gunicorn --bind 0.0.0.0:$PORT --workers 1 --threads 8 --timeout 0 --graceful-timeout 9 config.wsgi:application"
db:
  mode: none
secrets:
  items:
    - name: DATABASE_URL

config.wsgi:application はプロジェクトの WSGI モジュールに置き換えます。DEBUG は既定で無効にし、静的ファイルは whitenoise で配信します（STATIC_ROOT を設定し、ビルドで collectstatic を実行）。ALLOWED_HOSTS = ["*"] は維持してください。詳しい設定は Deploy Spec を参照してください。

SQLAlchemy / SQLModel / Flask-SQLAlchemy

ファイル SQLite を使う構成では、sqlalchemy-libsql-native を使って Managed SQLite に接続する方法があります。この方法は実験的な扱いです。接続設定の変更に加えて、モデル・クエリ・マイグレーションが動作するかを確認してください。AI エージェントに、必要な変更と互換性の確認を依頼してください。

Streamlit / Gradio

Streamlit は WebSocket が必須のため、現在は動きません。Gradio は 4 以上を検証中です。

Node.js

共通

NODE_ENV は自動設定されません。keelson.yaml で宣言します。未設定だと Express などがスタックトレースをレスポンスに含めます。

env:
  NODE_ENV: "production"

Keelson 上でのビルドには npm を使います。pnpm-lock.yaml / yarn.lock しかない場合は、事前チェックでデプロイが止まります。package-lock.json を生成し、npm で依存のインストールとビルドが成功するかを確認してください。静的サイトは、手元で pnpm や Yarn を使ってビルドしたものも配信できます。詳しくは依存関係のインストールを参照してください。

Express

command: "npm start"          # package.json: "start": "node server.js"

エラーハンドラでスタックを返さない
クライアント IP や HTTPS の判定に trust proxy を使う場合は、実際のプロキシ経路と転送ヘッダーに合わせて設定する。固定値 1 で正しく判定できるとは限りません（Express の公式ガイド）
アプリ独自のセッションや JWT に使うシークレットは secrets で宣言する

Next.js

ビルドして next start で起動します。next dev は本番用ではありません。

command: "npm run start"      # package.json: "start": "next start -p $PORT"

npm run build がビルド時に自動実行されます。.next/ が生成されることを確認します
"start": "next dev" になっていたら直します
KEELSON_DB_URL をサーバー側で読みます。NEXT_PUBLIC_* に入れるとブラウザに配布されます

Prisma

Managed SQLite に接続する場合も、Prisma の provider は "sqlite" を使います。変更するのは接続方法です。ローカルファイルへの接続を、@prisma/adapter-libsql を渡した Prisma Client に変更し、KEELSON_DB_URL と KEELSON_DB_AUTH_TOKEN を使います（接続方法）。

@prisma/adapter-libsql と @prisma/client は対応するバージョンにそろえます（6.x で検証済み）。アダプターの設定だけで、Prisma のマイグレーションがリモート DB に適用されるわけではありません。利用中のバージョンでのクエリの動作と、生成した SQL を Managed SQLite に適用する方法を、AI エージェントに確認してもらってください。

Go

Keelson が go build -o /workspace/app . でビルドし、./app で起動します。

runtime: go-slim
command: "./app"

CGO_ENABLED=0 でビルドされます。mattn/go-sqlite3 などの cgo SQLite ドライバは使えません。Managed SQLite には純 Go の libSQL クライアントを使います
ListenAndServe を放置せず、signal.NotifyContext と server.Shutdown で 10 秒以内に処理中のリクエストを処理し切ります
GORM などの ORM を使っている場合は、接続先 DB とドライバの互換性を確認します。Managed SQLite に接続できない場合は、database/sql と純 Go の libSQL クライアントを使う実装に変更します

静的サイト / SPA

Vite、Next.js の静的エクスポート、Astro などは、手元でビルドした出力を assets.dir に指定してデプロイします。command のない静的サイトでは、Keelson 上で依存パッケージのインストールやビルドは行われません。

静的サイトには type: web が必要です。dist/ を .gitignore に入れていても、assets.dir に指定していれば送信対象に含まれます。設定例は keelson.yaml の設定を参照してください。

静的な画面と API サーバーを組み合わせるハイブリッド構成でも、画面のファイルは手元でビルドしてからデプロイします。