Auto-hébergement de Firecrawl

Auto-hébergez Firecrawl avec Docker Compose lorsque vous devez garder le contrôle sur le code source ou l’infrastructure. Ce guide utilise la version v2.11.162, démarre l’API sur http://localhost:3002 et vérifie qu’une requête POST /v2/scrape renvoie du Markdown.

Ce démarrage rapide pour réseau de confiance désactive l’authentification de l’API et ne constitue pas une architecture de production. Il démarre sans stockage persistant, TLS, haute disponibilité ni toutes les fonctionnalités de Firecrawl Cloud.

Choisir entre l’auto-hébergement et Firecrawl Cloud

Auto-hébergez Firecrawl si

Vous souhaitez contrôler le code source ou l’infrastructure. Ce guide vous permet d’exécuter l’API et les services qui la prennent en charge sur votre machine.
Vous êtes à l’aise avec l’exploitation de la pile. Vous serez responsable des mises à niveau, de la sécurité, du stockage, de la supervision et de la récupération.
Vous souhaitez valider Firecrawl dans votre environnement. Commencez par faire fonctionner la configuration de référence, puis définissez les mesures de contrôle dans Avant la production.

Choisissez Firecrawl Cloud si vous souhaitez démarrer le scraping sans gérer d’infrastructure. Consultez Open Source vs Cloud pour connaître les différences de fonctionnalités. Notre recommandation : auto-hébergez Firecrawl si l’accès au code source ou le contrôle de l’infrastructure justifie l’effort opérationnel. Si vous recherchez le chemin pris en charge le plus rapide vers la production, commencez avec Firecrawl Cloud.

Ce qu’implique l’auto-hébergement

Vous êtes responsable des mises à niveau, des secrets, du stockage, de la supervision, de la récupération et de la réponse aux incidents.
Le scraping envoie toujours des requêtes sortantes vers les sites web cibles. Les fournisseurs facultatifs de proxy, de parsing ou d’IA ajoutent d’autres flux de données.
Ce guide simplifie volontairement la première exécution. Faites fonctionner un premier scrape, puis modifiez une seule décision à la fois.
Les commandes sont épinglées à v2.11.162. Une autre version peut utiliser un contrat Compose différent.

Auto-hébergez Firecrawl avec Docker Compose

Commencez avec ces valeurs par défaut

Version : Firecrawl v2.11.162. Figez d’abord le code et la configuration. Effectuez la mise à niveau après avoir examiné le fichier docker-compose.yaml et les notes d’auto-hébergement de la version cible.
Authentification de l’API : désactivée pour cette exécution locale. Ne l’ajoutez qu’avec une conception complète et prise en charge de la gestion des identités et de la base de données ; une seule variable d’environnement ne suffit pas.
File d’attente : PostgreSQL. Conservez-la, sauf si vous souhaitez délibérément exploiter le backend FoundationDB facultatif.
Interface d’administration de la file d’attente : désactivée. Ne l’activez qu’avec une BULL_AUTH_KEY robuste et des contrôles réseau.
Fournisseurs d’IA et de scraping avancé : non configurés. Ajoutez un fournisseur lorsqu’une fonctionnalité dont vous avez besoin l’exige.

Gardez la première exécution simple : faites fonctionner un scrape, puis ajoutez ce dont votre cas d’utilisation a besoin.

Prérequis

Avant de démarrer, installez :

Git
Docker Engine ou Docker Desktop
Docker Compose v2, appelé avec docker compose
curl pour les requêtes de vérification

Assurez-vous que le port 3002 est disponible et que Docker dispose de suffisamment de ressources pour créer et exécuter plusieurs services. Firecrawl ne publie pas de configuration minimale vérifiée pour l’hôte de cette pile.

Clonez la version validée

Ce guide a été vérifié avec Firecrawl v2.11.162. Clonez cette version précise afin de maintenir le code, les commandes et la configuration synchronisés :

git clone https://github.com/firecrawl/firecrawl.git
cd firecrawl
git checkout v2.11.162

Vous souhaitez utiliser une autre version ? Consultez son fichier docker-compose.yaml et les notes sur l’auto-hébergement avant de réutiliser ces valeurs.

Configurer le déploiement d’évaluation

Créez le fichier .env minimal requis à la racine du dépôt :

cat > .env <<'EOF'
USE_DB_AUTHENTICATION=false
POSTGRES_USER=postgres
POSTGRES_PASSWORD=replace-with-at-least-32-random-characters
POSTGRES_DB=postgres
EOF

Remplacez le mot de passe PostgreSQL avant de démarrer la pile et ne versionnez pas .env. Conservez POSTGRES_DB=postgres pour v2.11.162, car la configuration pg_cron incluse cible cette base de données. Compose transmet ces valeurs à l’API et au service PostgreSQL.

apps/api/.env.example est destiné au développement de l’API, et non à servir directement de fichier Compose. Lors de cette première exécution, l’authentification à la base de données est désactivée : les requêtes n’ont donc besoin ni d’une clé API ni d’un en-tête Authorization.

Ne définissez pas NUQ_BACKEND ni BULL_AUTH_KEY. Vous utiliserez la file d’attente PostgreSQL sans lancer l’interface d’administration de la file d’attente — moins de composants à gérer pour le premier scrape.

Créer et démarrer Firecrawl

Compilez le code source récupéré, puis démarrez l’ensemble en arrière-plan :

docker compose up --build -d
docker compose ps --all

Les avertissements concernant les variables facultatives non définies sont normaux pour cette configuration de référence. docker compose ps --all devrait afficher l’API et les services auxiliaires en cours d’exécution, ainsi que les services d’initialisation ponctuelle terminés. Si certains services démarrent encore, patientez un peu.

Vérifier l’accessibilité de l’API

Assurez-vous d’abord que l’API répond à une requête HTTP :

curl \
  --fail \
  --silent \
  --show-error \
  --max-time 5 \
  http://localhost:3002/v0/health/readiness

Réponse attendue :

{"status":"ok"}

Il s’agit d’un contrôle de disponibilité, et non d’un test de bout en bout. Il ne vérifie ni Redis, PostgreSQL, RabbitMQ, Playwright, ni les workers ou l’accès au réseau sortant. Exécutez le scrape ci-dessous avant de considérer le déploiement comme opérationnel.

Effectuer un test de validation fonctionnel

Testez maintenant l’élément essentiel : un véritable scrape. Le délai d’expiration de la requête est en millisecondes ; celui du client curl est en secondes et légèrement plus long :

curl \
  --fail-with-body \
  --silent \
  --show-error \
  --max-time 75 \
  -X POST \
  http://localhost:3002/v2/scrape \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "formats": ["markdown"],
    "timeout": 60000
  }'

Une réponse réussie se présente ainsi :

{
  "success": true,
  "data": {
    "markdown": "...",
    "metadata": {
      "statusCode": 200
    }
  }
}

Cela vérifie à la fois l’API, le pipeline de scraping, un parcours du moteur de scraping et l’accès sortant. Les métadonnées exactes peuvent varier selon la réponse de la cible. Si vous obtenez ces champs indiquant la réussite, Firecrawl fonctionne de bout en bout sur votre infrastructure. Conservez cette référence, puis choisissez les éléments à ajouter.

Prise en charge des fonctionnalités en auto-hébergement

Votre premier scrape fonctionne. N’ajoutez une fonctionnalité que lorsque vous en avez besoin, pas simplement parce qu’elle existe :

Si vous avez besoin de	Décision
Routes principales de scrape, crawl, cartographie et recherche	Conservez la pile par défaut. Les traitements Fetch et Playwright sont inclus.
Extraction ou formats basés sur un LLM	Connectez un fournisseur compatible avec OpenAI ou Ollama, puis testez ce chemin séparément.
Fire-engine ou son comportement anti-bot avancé	Exécutez et configurez ce service séparément : il n’est pas inclus.
Captures d’écran ou actions sur les pages	Non disponibles dans la pile par défaut. Fetch et Playwright signalent tous deux l’absence de prise en charge ; tous deux nécessitent Fire-engine.
Agent, Browser, interact, retour ou formats spécialisés pour les produits, menus, contenus audio et vidéo	Utilisez Firecrawl Cloud ou vérifiez les exigences du service externe pour la fonctionnalité concernée.

Pour une comparaison plus générale des produits, consultez Open Source vs Cloud. Pour la configuration propre à une version, utilisez le fichier docker-compose.yaml épinglé comme référence complémentaire.

Avant la production

Compose vous permet de démarrer rapidement. Avant d’exposer l’API en dehors d’un réseau de confiance, la mise en production exige quelques choix explicites :

Si les données doivent survivre au remplacement d’un service, ajoutez un stockage persistant pour PostgreSQL, Redis et RabbitMQ, puis définissez et testez les procédures de sauvegarde et de restauration. Le fichier Compose fourni n’ajoute pas ces volumes.
Si des utilisateurs ou des réseaux non fiables peuvent accéder à l’API, mettez en place un mécanisme d’authentification pris en charge, des contrôles d’accès réseau et TLS au niveau d’un proxy inverse ou d’un ingress. N’exposez pas publiquement cette référence non authentifiée.
Si vous avez des exigences de disponibilité ou de capacité, définissez des objectifs de disponibilité, une supervision, le dimensionnement des ressources, des seuils de mise à l’échelle ainsi que des procédures de mise à niveau et de restauration. Les limites définies dans Compose ne constituent pas des exigences minimales vérifiées.
Si la localisation des données ou la conformité est importante, cartographiez les requêtes vers les sites web cibles et chaque fournisseur facultatif d’IA, de proxy ou d’analyse avant de les activer.
Si les secrets doivent être gérés de manière centralisée, déplacez le mot de passe de la base de données hors de .env vers le système de gestion des secrets de votre plateforme.

Il s’agit de décisions d’infrastructure. Aucun paramètre unique dans .env ne rend la pile prête pour la production.

Étapes suivantes

Vous êtes encore en phase d’évaluation ? Gardez l’API sur un réseau de confiance et exécutez docker compose down une fois terminé.
Vous ajoutez une fonctionnalité open source ? Utilisez Prise en charge des fonctionnalités en auto-hébergement pour identifier le fournisseur ou service requis, puis testez cette option séparément.
Vous modifiez le code de Firecrawl ? Passez à Exécution locale pour accéder à l’environnement de développement des contributeurs.
Vous connectez un client ? Configurez la CLI Firecrawl ou le serveur MCP local avec l’URL vérifiée de votre API.
Vous passez à Kubernetes ? Commencez par les références Kubernetes ou Helm versionnées liées depuis SELF_HOST.md, puis définissez explicitement les décisions de production ci-dessus pour votre plateforme.
Vous souhaitez une infrastructure gérée ou des capacités exclusives au Cloud ? Comparez Open Source vs Cloud.
Vous passez en production ? Prenez toutes les décisions indiquées dans Avant la production avant d’exposer l’API.

Dépannage

Vous contournez l’authentification

Si cet avertissement s’affiche avec USE_DB_AUTHENTICATION=false, vous êtes dans le scénario prévu lors de la première exécution. Les requêtes utilisent une identité auto-hébergée et ne nécessitent aucune clé API. Si l’API est accessible depuis un réseau non fiable, arrêtez-vous et mettez en place les contrôles décrits dans Avant la mise en production.

Les conteneurs Docker ne démarrent pas

Si un service exécuté en continu s’arrête, vérifiez l’état du conteneur et les journaux récents :

docker compose ps --all
docker compose logs --tail=200

Si la révision source diffère, récupérez v2.11.162 ou utilisez la configuration de cette version.
Si une compilation ou un conteneur manque de ressources, augmentez les ressources CPU, mémoire ou disque allouées à Docker.
Si PostgreSQL échoue, vérifiez la syntaxe de .env, conservez POSTGRES_DB=postgres et assurez-vous que les valeurs du nom d’utilisateur et du mot de passe sont cohérentes.

Problèmes de connexion à Redis

Si un conteneur ne parvient pas à se connecter à Redis, conservez l’adresse du service Compose redis://redis:6379. localhost désigne ce conteneur, et non le service Redis.

docker compose ps redis
docker compose logs --tail=100 redis

Si vous avez ajouté REDIS_URL ou REDIS_RATE_LIMIT_URL, supprimez ce remplacement pour rétablir la valeur par défaut, ou utilisez une adresse résoluble depuis le réseau Compose.

Le point de terminaison de l’API ne répond pas

Si le port 3002 ne répond pas, vérifiez le conteneur de l’API et ses journaux :

docker compose ps api
docker compose logs --tail=200 api

Si un autre processus utilise le port 3002, arrêtez-le ou modifiez le port publié en conséquence. Lors du démarrage initial, ne réessayez qu’une fois le conteneur d’API signalé comme étant en cours d’exécution. Si /v0/health/readiness réussit, mais que /v2/scrape échoue, inspectez les journaux de l’API et de Playwright, car le point de terminaison d’accessibilité ne valide pas ces dépendances :

docker compose logs --tail=200 api playwright-service

La requête de scrape expire

Si le scrape expire, vérifiez que le déploiement peut accéder à https://example.com et que les services d’API et Playwright sont en cours d’exécution. Définissez --max-time de curl sur une valeur supérieure au timeout du corps de la requête afin que l’API puisse renvoyer sa propre réponse d’expiration.

Prise en main

Points de terminaison de base

Plus

Démarrages rapides

Guides développeur

Webhooks

Cas d'utilisation

Autres

Contribuer

Auto-hébergement de Firecrawl

Choisir entre l’auto-hébergement et Firecrawl Cloud

Auto-hébergez Firecrawl si

Ce qu’implique l’auto-hébergement

Auto-hébergez Firecrawl avec Docker Compose

Commencez avec ces valeurs par défaut

Prérequis

Clonez la version validée

Configurer le déploiement d’évaluation

Créer et démarrer Firecrawl

Vérifier l’accessibilité de l’API

Effectuer un test de validation fonctionnel

Prise en charge des fonctionnalités en auto-hébergement

Avant la production

Étapes suivantes

Dépannage

Vous contournez l’authentification

Les conteneurs Docker ne démarrent pas

Problèmes de connexion à Redis

Le point de terminaison de l’API ne répond pas

La requête de scrape expire

​Choisir entre l’auto-hébergement et Firecrawl Cloud

​Auto-hébergez Firecrawl si

​Ce qu’implique l’auto-hébergement

​Auto-hébergez Firecrawl avec Docker Compose

​Commencez avec ces valeurs par défaut

​Prérequis

​Clonez la version validée

​Configurer le déploiement d’évaluation

​Créer et démarrer Firecrawl

​Vérifier l’accessibilité de l’API

​Effectuer un test de validation fonctionnel

​Prise en charge des fonctionnalités en auto-hébergement

​Avant la production

​Étapes suivantes

​Dépannage

​Vous contournez l’authentification

​Les conteneurs Docker ne démarrent pas

​Problèmes de connexion à Redis

​Le point de terminaison de l’API ne répond pas

​La requête de scrape expire

Choisir entre l’auto-hébergement et Firecrawl Cloud

Auto-hébergez Firecrawl si

Ce qu’implique l’auto-hébergement

Auto-hébergez Firecrawl avec Docker Compose

Commencez avec ces valeurs par défaut

Prérequis

Clonez la version validée

Configurer le déploiement d’évaluation

Créer et démarrer Firecrawl

Vérifier l’accessibilité de l’API

Effectuer un test de validation fonctionnel

Prise en charge des fonctionnalités en auto-hébergement

Avant la production

Étapes suivantes

Dépannage

Vous contournez l’authentification

Les conteneurs Docker ne démarrent pas

Problèmes de connexion à Redis

Le point de terminaison de l’API ne répond pas

La requête de scrape expire