SimplePDF Copilotをセルフホストする方法

Benjamin André-Micolon

SimplePDF CopilotはSimplePDFエディターにAIチャットサイドバーを追加するためのMITライセンスのリファレンス実装です。Copilotアプリをフォークし、自社のインフラにデプロイし、独自のAIプロバイダーを接続し、完成した文書を独自のストレージにルーティングできます。

SimplePDFエディター自体はホスト型のiframeのままです。Copilotをセルフホストするということは、エディター周辺のチャットアプリ、AIルーティング、プロンプト、ツール、ストレージフローを自分で所有するということです。

本ガイドはlocalhostから本番までの道のりをカバーします。

Claude Code、Codex、その他のエージェント型コーディングツールを使用している場合は、fork-and-goスキルを指定してください。このスキルはエージェントを質問1つずつフォーク、構成、デプロイのフローへ導きます。

セルフホストする対象

Copilotチャットアプリ。 自社インフラ上で動作します。あなたが管理します。
システムプロンプトとツールレジストリ。 あなたのCopilotデプロイに存在します。あなたが管理します。
AIルーティング。 サーバー側、ブラウザBYOK、またはローカルエンドポイント。あなたが管理します。
完成した文書のストレージ。 デフォルトはSimplePDFストレージ、BYOS有効時は自社ストレージ。BYOSが有効な場合はあなたが管理します。
SimplePDFエディターiframe。 SimplePDFによるホストのままです。

前提条件

SimplePDF Proプラン以上。Copilotを自社ドメインで動作させるには、ホワイトラベリング、エディターのプログラム的制御、SimplePDFダッシュボードでの許可オリジンが必要です。これらの機能がないと、エディターはホスト型デモのオリジンかhttp://localhost:3001でのみ読み込まれます。
AIプロバイダーのキー、BYOKフロー、またはローカルのOpenAI互換エンドポイント。Anthropic、OpenAI、DeepSeek、Google Gemini、Mistralがあらかじめ組み込まれています。
Node 24ランタイム。現在のCopilotデプロイテンプレートはNode 24を使用し、アプリは無修正でDigitalOcean App Platform、Cloudflare Containers、Vercel、Render、fly.io、Railway、セルフホストのDocker上で動作します。

ステップ1：ローカルでデモを実行する

リポジトリをクローンし、共有のSimplePDFデモワークスペースに対してデモを実行します。このステップではSimplePDFアカウントは不要です。

git clone https://github.com/SimplePDF/simplepdf-embed.git
cd simplepdf-embed/copilot
npm install
cp .env.example .env
printf "\nVITE_SIMPLEPDF_COMPANY_IDENTIFIER=spdf-copilot\n" >> .env
npm run dev

開発サーバーはhttp://localhost:3001で動作します。チャットのサイドバーを開き、プロバイダーキーを貼り付けるか、OllamaやLM StudioのようなローカルのOpenAI互換エンドポイントを指定します。

デモワークスペースはhttp://localhost:3001という1つのローカルオリジンのみをホワイトリスト化しています。それ以外のポートやホストはiframeによって拒否されます。自社ドメインで実行するには、ステップ2に進んでください。

ステップ2：SimplePDFアカウントを設定する

Pro以上を契約します。SimplePDFのダッシュボードから：

companyIdentifierをコピーします。これはVITE_SIMPLEPDF_COMPANY_IDENTIFIERに設定する値です。
配信オリジン（例：https://app.example.com）をホワイトリストに追加します。iframeはホワイトリスト化されていないオリジンでの読み込みを拒否します。
任意でブランドをカスタマイズして、エディターからSimplePDFのクロームを取り除きます。

ステップ3：ホストにデプロイする

最も速い方法はSimplePDF CopilotのREADMEにあるDigitalOceanのワンクリックデプロイボタンです。DigitalOceanはcopilot/フォルダーをNode 24でビルドし、環境変数の入力を求めます。

VITE_SIMPLEPDF_COMPANY_IDENTIFIER（必須）：SimplePDFの会社識別子。
SHARED_API_KEYS（任意）：各訪問者にプロバイダーキーの貼り付けを求めずにデモを共有できるようにします。
REDIS_URL（任意）：レート制限カウンターをコンテナ間で永続化します。
IP_HASH_SALT（REDIS_URLが設定されている場合は必須）：永続化されたIPハッシュにソルトを付与します。

その他のデプロイ先（Cloudflare Containers、Vercel、Render、fly.io、Railway、セルフホストのDockerなど）の場合は、READMEのその他のデプロイ先のセクションに従ってください。

デプロイが完了したら、アプリを開く前に、デプロイされたオリジン（例：https://copilot.example.com）をSimplePDFダッシュボードのホワイトリストに追加してください。

ステップ4：AIプロバイダーを接続する

サーバー側のストリーミングはsrc/routes/api/chat.tsにあります。プロバイダーの選択はsrc/server/language_model.tsにあります。アプリケーションがプロバイダーキー、レート制限、ログ、テナントごとの設定を所有する場合は、このパスを使用してください。

ユーザー提供のキーの場合、src/lib/byok/にあるブラウザ直結BYOKパスがブラウザからプロバイダーを呼び出し、サーバーをバイパスします。これはOllamaやLM Studioなどのローカル OpenAI互換エンドポイントにも適した形です。

3つのルート、3つの信頼境界：

サーバー側のプロバイダーキー。 アプリがプロバイダーアカウントとテナントポリシーを所有します。AIトラフィックは自社サーバーを通ってAIプロバイダーへ流れます。
ブラウザBYOK。 ユーザーが自分のプロバイダーキーを持ち込みます。AIトラフィックはブラウザから直接、選択されたプロバイダーへ流れ、自社サーバーをバイパスします。
ローカルのOpenAI互換エンドポイント。 AIトラフィックはユーザーの端末またはネットワーク上にとどまります。ブラウザはローカルエンドポイントと通信し、サードパーティのAIプロバイダーには何も送信されません。

ステップ5：送信を独自のストレージにルーティングする

デフォルトでは、完成した文書はSimplePDFのストレージに着地します。Pro以上のBring Your Own Storageを使用すると、完成した文書は事前署名されたURLを介してブラウザから直接、構成済みのストレージへアップロードされます。

これは完成した文書のストレージパスを変更するものです。これ自体は、構成済みのAIプロバイダーへ送信される文書コンテキストを制御しません。AIルートはステップ4で別途構成してください。

ストレージを構成する：

ステップ6：本番セットアップを検証する

ユーザーにアプリを共有する前に、エンドツーエンドで全体のパスを検証してください：

ホワイトリスト化されたオリジンから、デプロイされたCopilotのURLを開きます。
SimplePDFエディターのiframeがオリジンエラーなしで読み込まれることを確認します。
テスト用プロンプトを送信し、選択したAIルートが使用されることを確認します。
フィールドに入力し、その値がPDFエディターに表示されることを確認します。
テスト文書を送信またはダウンロードします。
BYOSが有効な場合、完成したPDFがSimplePDFストレージではなく自社ストレージに着地することを確認します。
ログをレビューし、永続化したくないシークレット、文書テキスト、PHI、PII、その他の機微なデータがないか確認します。

システムプロンプトとツールをカスタマイズする

Copilotが自社インフラ上でエンドツーエンドに動作するようになったら、次のカスタマイズ層はシステムプロンプトとモデルに公開されるツールレジストリです。どちらもsrc/server/tools.tsにあります。チャットUI自体はsrc/components/chat_pane.tsxです。ロケールはsrc/locales/にあります。

その他のすべて（フォーク、構成、Copilotを非自明な製品サーフェスに適合させる作業）については、fork-and-goスキルがAIコーディングアシスタントを通じて、決定を1つずつ進めながら作業を導きます。

トラブルシューティング

エディターのiframeが読み込まれない

親アプリのオリジンがSimplePDFダッシュボードのホワイトリストに登録されているか確認してください。ローカルのデモワークスペースはhttp://localhost:3001のみ許可しています。

ローカルデモは動作するが本番では動作しない

VITE_SIMPLEPDF_COMPANY_IDENTIFIERが自社のSimplePDF会社識別子を使用していること、本番ドメインが許可オリジンのリストに含まれていることを確認してください。

ユーザーがAIキーの貼り付けを求められる

これはBYOKモードでは想定どおりの動作です。事前構成済みのデモを共有するには、SHARED_API_KEYSを構成し、?share=<id>のURLフローを使用してください。

デプロイのたびにレート制限がリセットされる

メモリ内のレート制限はアプリの再起動時にリセットされます。コンテナ間または再起動をまたいでカウンターを永続化する必要がある場合は、REDIS_URLとIP_HASH_SALTを使用してください。

完成したPDFが自社ストレージに到達しない

Bring Your Own StorageがSimplePDFで構成されていることを確認し、本番のフォームを使用する前に小さなPDFでテストしてください。

以上です。Copilotアプリは自社のインフラ上で動作し、構成済みのAIルートを使用し、BYOSが有効な場合は完成した文書を自社のストレージに送信できます。

ご質問がございましたら、お気軽にsupport@simplepdf.comまでご連絡ください。