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

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

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

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

全フレームワーク共通

• 0.0.0.0 と環境変数 PORT で指定されたポートで待ち受ける。 127.0.0.1 ではリクエストが届きません
• 起動コマンドにインストール処理を含めない。 requirements.txt / package.json / go.mod からビルド時に入ります
• 停止は SIGTERM → 10 秒後に SIGKILL。 処理中のリクエストは 10 秒以内に終わらせます
• 1 vCPU。 worker 数は 1 にします
• デバッグモードの既定は off。 デバッグ画面は環境変数（DB の認証トークンを含む）を表示することがあります
• 「Keelson 上か」の判別は KEELSON_MODE。 値が keelson ならプラットフォーム上です。DEBUG をこの目的に使うとローカルで起動できなくなります

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 は現在未対応です。Keelson の Managed SQLite（libSQL）と Django ORM の互換性に制約があるためです。

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"

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

Express

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

• エラーハンドラでスタックを返さない
• app.set("trust proxy", 1) でクライアント IP / プロトコルをエッジから受け取る
• セッションや 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

provider = "sqlite" のままでは動きません。@prisma/adapter-libsql を @prisma/client と同じメジャーバージョンにそろえて使います（6.x で検証済み）。利用中のバージョンでクエリやマイグレーションが動作するかを、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 を使っている場合は database/sql + libSQL に置き換えます

静的サイト / SPA

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

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

関連ページ

• 対応アプリと制約
• データベース（Managed SQLite）
• Keelson Deploy Spec — AI エージェント向けの正本