# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Nature du dépôt

Ce dossier n'est **pas** le code source de Firecrawl. C'est un espace de travail de référence pour l'instance Firecrawl **self-hosted** de l'utilisateur, composé de :

- **Snapshots de la documentation officielle** (`Self hosting.md`, `run-locally.md`, `Deep Research.md`, `Full-Stack Templates.md`, `SEO Platforms.md`) — copies de pages de docs.firecrawl.dev. L'index complet de la doc est disponible sur https://docs.firecrawl.dev/llms.txt.
- **`docker-compose.yaml`** — copie du compose upstream, définissant la stack complète de l'instance self-hosted.
- **`Ancienne-conf/firecrawl/`** — ancienne config de production (instable : autoheal agressif, limites mémoire trop serrées sur Redis/RabbitMQ, concurrence surdimensionnée). Conservée comme référence, ne pas la redéployer.
- **`Nouvelle-conf/firecrawl/`** — config de production corrigée, à déployer et faire évoluer (runbook complet : `INSTALL.md`). Cible : Ubuntu 12 CPU / 32G avec **Nginx hors Docker** (pas de Traefik). Contrainte critique : `/` ne fait que 19,5G — data-root Docker déplacé sur `/data/docker`, stack et données sur `/data/firecrawl/`. L'API n'écoute que sur `127.0.0.1:3002` (app seo-insight co-localisée) ; l'accès externe passe par le vhost `nginx/crawl.elevaseo.app.conf` qui vérifie la clé `FIRECRAWL_API_KEY`, car le self-hosted n'a aucune auth applicative — ne jamais mapper `0.0.0.0:3002`. Le compose exige 3 secrets dans `.env` (syntaxe `:?`) : `BULL_AUTH_KEY`, `POSTGRES_PASSWORD`, `SEARXNG_SECRET` ; `FIRECRAWL_API_KEY` est consommée par Nginx et l'app, pas par le compose. Valider toute modification avec `docker compose config --quiet` (en exportant des valeurs factices pour les secrets).
- **`Nouvelle-conf/SEO-INSIGHT-REQUIREMENTS.md`** — contrat d'intégration avec l'app seo-insight (endpoints appelés, dimensionnement multi-tenant, options réseau A/B). À relire avant tout changement de tuning ou d'exposition réseau de la stack.

Ne pas chercher de code applicatif, de tests ou de linter ici : il n'y en a pas. Pour toute question sur les internals de Firecrawl, se référer au dépôt upstream (github.com/firecrawl/firecrawl) ou à la doc.

## Piège principal du docker-compose.yaml

Le compose référence des builds locaux (`build: apps/api`, `build: apps/playwright-service-ts`, `build: apps/nuq-postgres`) — **ces dossiers n'existent pas ici**. `docker compose build` échouera depuis ce dossier. Deux options :

1. Basculer sur les images publiées en commentant les `build:` et décommentant les `image:` (`ghcr.io/firecrawl/firecrawl`, `ghcr.io/firecrawl/playwright-service:latest`, `ghcr.io/firecrawl/nuq-postgres:latest`) ;
2. Cloner le dépôt firecrawl complet si un build local est réellement nécessaire.

## Architecture de la stack self-hosted

Services définis dans `docker-compose.yaml` (réseau `backend`) :

- **api** (port 3002, `node dist/src/harness.js --start-docker`) — serveur API + workers de crawl dans le même conteneur. Dépend de redis, playwright-service et rabbitmq.
- **playwright-service** (port interne 3000) — rendu navigateur pour les pages JS et les screenshots.
- **redis** — file de jobs et rate limiting.
- **rabbitmq** — messagerie interne (NUQ).
- **nuq-postgres** — Postgres avec le schéma de queue NUQ (`apps/nuq-postgres/nuq.sql` upstream).
- **foundationdb** + **foundationdb-init** (expérimental) — backend de queue alternatif, activé via `NUQ_BACKEND=fdb` ; destiné à remplacer nuq-postgres à terme.

Configuration via un `.env` à la racine (template : `apps/api/.env.example` upstream). Minimum requis : `PORT=3002`, `HOST=0.0.0.0`, `USE_DB_AUTHENTICATION=false`. Les warnings « You're bypassing authentication » et « Supabase client is not configured » sont normaux en self-hosted.

## Commandes courantes

```bash
docker compose up -d                      # démarrer la stack
docker logs <container>                   # diagnostiquer un conteneur

curl http://localhost:3002/test           # health check → "Hello, world!"
curl -X POST http://localhost:3002/v2/crawl \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://docs.firecrawl.dev"}'   # test de crawl
```

UI d'admin des queues : `http://localhost:3002/admin/{BULL_AUTH_KEY}/queues`.

## Limites du self-hosting (vs cloud)

- Endpoints `/agent` et `/browser` non supportés ; pas d'accès à Fire-engine (anti-bot, rotation IP avancée).
- Fonctionnalités IA (format JSON au scrape, `/extract`, summary, branding, change tracking) : nécessitent `OPENAI_API_KEY`, un endpoint OpenAI-compatible (`OPENAI_BASE_URL`) ou Ollama (`OLLAMA_BASE_URL`, expérimental).
- `/search` : passe par Google en direct, ou par un serveur SearXNG (`SEARXNG_ENDPOINT`) avec le format JSON activé.
- Screenshots : OK tant que playwright-service tourne.