メインコンテンツへスキップ

コントリビューターの方へ

Firecrawl へようこそ 🔥!プロジェクトをローカル環境にセットアップして手元で実行し、コントリビュートするための手順を紹介します。 コントリビュートの流れは他のオープンソースリポジトリと同様です。Firecrawl をフォークし、変更し、テストを実行して、PR を送ってください。 質問がある場合や参加のサポートが必要な場合は、Discord コミュニティにこちらから参加するか、GitHub でこちらから Issue を作成してください。

Firecrawl をセルフホストする

ローカルでの実行方法は SELF_HOST.md を参照してください。

なぜ?

厳格なセキュリティポリシーにより、データを管理された環境内に留める必要がある組織にとって、Firecrawl のセルフホスティングは特に有益です。セルフホスティングを検討すべき主な理由は次のとおりです:
  • セキュリティとコンプライアンスの強化: セルフホスティングにより、すべてのデータの取り扱いと処理を社内外の規制に適合させ、機密情報を自社の安全なインフラ内に保つことができます。なお、Firecrawl は Mendable の製品であり、SOC 2 Type II 認証に準拠しているため、プラットフォームはデータセキュリティ管理に関する高い業界基準を満たしています。
  • サービスのカスタマイズ: セルフホスティングにより、Playwright サービスなどを特定のニーズに合わせて調整し、標準的なクラウド提供ではサポートされない可能性のあるユースケースにも対応できます。
  • 学習とコミュニティへの貢献: 自身でインスタンスを構築・運用することで、Firecrawl の動作をより深く理解でき、プロジェクトへのより実践的な貢献にもつながります。

留意事項

ただし、以下の制約や追加の責務がある点に注意してください。
  1. Fire-engine へのアクセス制限: 現時点では、自己ホスト型の Firecrawl インスタンスは Fire-engine を利用できません。Fire-engine には、IP ブロック対応、ボット検知メカニズムなどの高度な機能が含まれます。つまり、基本的なスクレイピングは可能でも、より複雑なケースでは追加の設定が必要になったり、サポート対象外となる場合があります。
  2. 手動設定が必要: 基本的な fetch および Playwright オプションを超えるスクレイピング手法を用いる場合は、.env ファイルでの手動設定が必要です。これは関連技術への深い理解を要し、セットアップに時間がかかる可能性があります。
Firecrawl の自己ホストは、スクレイピングやデータ処理環境を完全に制御したい方に最適ですが、追加の保守や設定作業というトレードオフが伴います。

手順

  1. まず、依存関係をインストールします
  1. 環境変数を設定する
ルートディレクトリに .env を作成し、apps/api/.env.example のテンプレートをコピーします 最初は、認証や任意のサブサービス(PDF 解析、JS ブロック機能、AI 機能)は設定しません
# .env

# ===== 必須環境変数 ======
PORT=3002
HOST=0.0.0.0

# 注意: PORTはメインAPIサーバーとワーカーのヘルスチェックエンドポイントの両方で使用されます

# DB認証を有効にするには、Supabaseのセットアップが必要です。
USE_DB_AUTHENTICATION=false

# ===== オプション環境変数 ======

## === AI機能(スクレイプ時のJSON形式、/extract API) ===
# AI機能を有効にするには、OpenAI APIキーをここに設定してください
# OPENAI_API_KEY=

# 実験的機能: Ollamaを使用
# OLLAMA_BASE_URL=http://localhost:11434/api
# MODEL_NAME=deepseek-r1:7b
# MODEL_EMBEDDING_NAME=nomic-embed-text

# 実験的機能: OpenAI互換APIを使用
# OPENAI_BASE_URL=https://example.com/v1
# OPENAI_API_KEY=

## === プロキシ ===
# PROXY_SERVERは完全なURL(例: http://0.1.2.3:1234)またはIPとポートの組み合わせ(例: 0.1.2.3:1234)を指定できます
# プロキシが認証不要の場合は、PROXY_USERNAMEとPROXY_PASSWORDのコメントアウトを解除しないでください
# PROXY_SERVER=
# PROXY_USERNAME=
# PROXY_PASSWORD=

## === /search API ===
# デフォルトでは、/search APIはGoogle検索を使用します。

# Googleの代わりにSearXNGを使用する場合は、JSON形式が有効なSearXNGサーバーを指定できます。
# enginesとcategoriesパラメータをカスタマイズすることもできますが、デフォルト設定でも問題なく動作します。
# SEARXNG_ENDPOINT=http://your.searxng.server
# SEARXNG_ENGINES=
# SEARXNG_CATEGORIES=

## === その他 ===

# Supabaseセットアップ(DB認証、高度なログ記録などをサポート)
# SUPABASE_ANON_TOKEN=
# SUPABASE_URL=
# SUPABASE_SERVICE_TOKEN=

# 認証をセットアップ済みで、実際のAPIキーでテストする場合に使用
# TEST_API_KEY=

# このキーでキュー管理パネルにアクセスできます。デプロイメントが公開されている場合は変更してください。
BULL_AUTH_KEY=CHANGEME

# これはdocker-compose.yamlによって自動設定されます。設定する必要はありません。
# PLAYWRIGHT_MICROSERVICE_URL=http://playwright-service:3000/scrape
# REDIS_URL=redis://redis:6379
# REDIS_RATE_LIMIT_URL=redis://redis:6379

# PDFの解析にllamaparseキーを使用する場合に設定
# LLAMAPARSE_API_KEY=

# サーバーのヘルスステータスメッセージをSlackに送信する場合に設定
# SLACK_WEBHOOK_URL=

# ジョブログなどのPostHogイベントを送信する場合に設定
# POSTHOG_API_KEY=
# POSTHOG_HOST=

## === システムリソース設定 ===
# 最大CPU使用率のしきい値(0.0-1.0)。CPU使用率がこの値を超えると、ワーカーは新しいジョブを拒否します。
# デフォルト: 0.8 (80%)
# MAX_CPU=0.8

# 最大RAM使用率のしきい値(0.0-1.0)。メモリ使用率がこの値を超えると、ワーカーは新しいジョブを拒否します。
# デフォルト: 0.8 (80%)
# MAX_RAM=0.8

# セルフホストインスタンスへのローカルWebhook送信を許可する場合に設定
# ALLOW_LOCAL_WEBHOOKS=true
  1. (オプション) TypeScript Playwright Service で実行する
    • docker-compose.yml を更新して、Playwright サービスを次のように変更します:
          build: apps/playwright-service
      
          build: apps/playwright-service-ts
      
      に変更
    • .env ファイルで PLAYWRIGHT_MICROSERVICE_URL を設定します:
      PLAYWRIGHT_MICROSERVICE_URL=http://localhost:3000/scrape
      
    • 必要に応じて、.env ファイルでプロキシサーバーも設定してください。
  2. Docker コンテナをビルドして起動します:
    docker compose build
    docker compose up
    
これにより、http://localhost:3002 でアクセス可能なローカルの Firecrawl インスタンスが起動します。 http://localhost:3002/admin/@/queues で Bull Queue Manager の UI を確認できます。
  1. (任意)API をテストする
crawl エンドポイントを試すには、次を実行してください:
  curl -X POST http://localhost:3002/v2/crawl \
      -H 'Content-Type: application/json' \
      -d '{
        "url": "https://docs.firecrawl.dev"
      }'

トラブルシューティング

このセクションでは、自己ホスト型の Firecrawl インスタンスをセットアップまたは実行する際によく発生する問題に対する解決策を紹介します。

Supabase クライアントが構成されていません

症状:
[YYYY-MM-DDTHH:MM:SS.SSSz]ERROR - 設定されていない Supabase クライアントにアクセスしようとしました。
[YYYY-MM-DDTHH:MM:SS.SSSz]ERROR - スクレイプイベントの挿入中にエラーが発生しました: エラー: Supabase クライアントが設定されていません。
説明: このエラーは、Supabase クライアントのセットアップが完了していないために発生します。スクレイプやクロールは問題なく実行できるはずです。現在、セルフホスト環境では Supabase の設定はできません。

認証を迂回しています

症状:
[YYYY-MM-DDTHH:MM:SS.SSSz]WARN - 認証を迂回しています
説明: このエラーは、Supabase クライアントのセットアップが完了していないために発生します。スクレイピングやクロールは問題なく実行できるはずです。現在、セルフホスト環境では Supabase の設定は行えません。

Docker コンテナが起動しない

症状: Docker コンテナが予期せず終了する、または起動に失敗する。 解決策: 次のコマンドで Docker のログを確認し、エラーメッセージがないか確認する:
docker logs [コンテナ名]
  • .env ファイルで必要な環境変数がすべて正しく設定されていることを確認してください。
  • docker-compose.yml に定義された Docker サービスが正しく設定され、必要なイメージが利用可能であることを確認してください。

Redis への接続問題

症状: タイムアウトや「Connection refused」など、Redis への接続に関するエラーが発生する。 解決策:
  • Docker 環境で Redis サービスが起動・稼働していることを確認する。
  • .env ファイルの REDIS_URL および REDIS_RATE_LIMIT_URL が正しい Redis インスタンスを指していることを確認する。
  • Redis のポートへの接続を遮断している可能性があるネットワーク設定やファイアウォールのルールを確認する。

API エンドポイントが応答しない

症状: Firecrawl インスタンスへの API リクエストがタイムアウトする、または応答がない。 解決策:
  • Docker コンテナのステータスを確認し、Firecrawl サービスが稼働していることを確認する。
  • .env ファイルの PORT と HOST の設定が正しいこと、また同じポートを他のサービスが使用していないことを確認する。
  • API リクエストを送信するクライアントからホストへアクセス可能であることを確認するため、ネットワーク構成を確認する。
これらの一般的な問題に対処することで、セルフホストの Firecrawl インスタンスのセットアップと運用をよりスムーズにできます。

Kubernetes クラスターに Firecrawl をインストールする(簡易版)

Kubernetes クラスターへの Firecrawl のインストール手順は、examples/kubernetes-cluster-install/README.md を参照してください。