> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-8bz2qg.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Auto-hébergement de Firecrawl
> Auto-hébergez Firecrawl avec Docker Compose, vérifiez un scrape local, comprenez les limites de la version open source et préparez la pile pour la production.
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](#before-production).
Choisissez [Firecrawl Cloud](https://firecrawl.dev) si vous souhaitez démarrer le scraping sans gérer d’infrastructure. Consultez [Open Source vs Cloud](/fr/contributing/open-source-or-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](https://git-scm.com/downloads)
* [Docker Engine](https://docs.docker.com/engine/install/) 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 :
```bash theme={null}
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 :
```bash theme={null}
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 :
```bash theme={null}
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 :
```bash theme={null}
curl \
--fail \
--silent \
--show-error \
--max-time 5 \
http://localhost:3002/v0/health/readiness
```
Réponse attendue :
```json theme={null}
{"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 :
```bash theme={null}
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 :
```json theme={null}
{
"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](/fr/contributing/open-source-or-cloud). Pour la configuration propre à une version, utilisez le fichier [`docker-compose.yaml`](https://github.com/firecrawl/firecrawl/blob/v2.11.162/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](#self-hosted-feature-support) pour identifier le fournisseur ou service requis, puis testez cette option séparément.
* **Vous modifiez le code de Firecrawl ?** Passez à [Exécution locale](/fr/contributing/guide) pour accéder à l’environnement de développement des contributeurs.
* **Vous connectez un client ?** Configurez la [CLI Firecrawl](/fr/sdks/cli#connect-the-cli-to-self-hosted-firecrawl) ou le [serveur MCP local](/fr/mcp-server/local#connect-mcp-to-self-hosted-firecrawl) 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`](https://github.com/firecrawl/firecrawl/blob/main/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](/fr/contributing/open-source-or-cloud).
* **Vous passez en production ?** Prenez toutes les décisions indiquées dans [Avant la production](#before-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](#before-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 :
```bash theme={null}
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.
```bash theme={null}
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 :
```bash theme={null}
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 :
```bash theme={null}
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.