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

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

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

# 自己ホストで Docker を使う場合は redis://redis:6379 を使用。ローカル実行時は redis://localhost:6379 を使用
REDIS_URL=redis://redis:6379

# 自己ホストで Docker を使う場合は redis://redis:6379 を使用。ローカル実行時は redis://localhost:6379 を使用
REDIS_RATE_LIMIT_URL=redis://redis:6379 
PLAYWRIGHT_MICROSERVICE_URL=http://playwright-service:3000/html

## DB 認証を有効にするには、Supabase の設定が必要です。
USE_DB_AUTHENTICATION=false

# ===== 任意の環境変数 ======

# Supabase の設定（DB 認証、詳細ログなどを有効化するために使用）
SUPABASE_ANON_TOKEN= 
SUPABASE_URL= 
SUPABASE_SERVICE_TOKEN=

# その他のオプション
# 認証を設定済みで、実際の API キーでテストしたい場合に使用
TEST_API_KEY=
# スクレイピングのレート制限をテストしたい場合に設定
RATE_LIMIT_TEST_API_KEY_SCRAPE=
# クローリングのレート制限をテストしたい場合に設定
RATE_LIMIT_TEST_API_KEY_CRAWL=
# LLM 依存の機能（画像の代替テキスト生成など）を使う場合に設定
OPENAI_API_KEY=
BULL_AUTH_KEY=@
# Logtail で基本的なロギングを設定する場合に使用
LOGTAIL_KEY=
# PDF 解析に使用したい LlamaParse のキーがある場合に設定
LLAMAPARSE_API_KEY=
# Slack にサーバーのヘルスステータスを送信したい場合に設定
SLACK_WEBHOOK_URL=
# PostHog にジョブログなどのイベントを送信したい場合に設定
POSTHOG_API_KEY=
# PostHog にジョブログなどのイベントを送信したい場合に設定
POSTHOG_HOST=

# Fire Engine クローズドベータを使用したい場合に設定
FIRE_ENGINE_BETA_URL=

# Playwright 用のプロキシ設定（代替として、リクエストごとに IP をローテーションする Oxylabs のようなプロキシサービスを使用可能）
PROXY_SERVER=
PROXY_USERNAME=
PROXY_PASSWORD=
# プロキシ帯域の節約のためにメディアリクエストをブロックしたい場合に設定
BLOCK_MEDIA=

# Firecrawl の自己ホスト版を使用する場合、Webhook の URL をここに設定
SELF_HOSTED_WEBHOOK_URL=

# トランザクションメール用の Resend API キー
RESEND_API_KEY=

# LOGGING_LEVEL は、システムが出力するログの詳細度を決定します。
# 利用可能なレベルは次のとおりです:
# NONE - ログを出力しません。
# ERROR - 特定の処理の失敗を示すエラーメッセージを記録します。
# WARN - エラーではないものの、潜在的に有害な状況を記録します。
# INFO - アプリケーションの進行状況を示す情報メッセージを記録します。
# DEBUG - 主にデバッグ用途で、システム内の処理フローに関する詳細情報を記録します。
# TRACE - DEBUG よりさらに詳細な情報を記録します。
# 上記のいずれかを LOGGING_LEVEL に設定して、ログ出力を制御してください。
LOGGING_LEVEL=INFO
  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を参照してください。