Saltar al contenido principal

¿Quieres contribuir?

¡Bienvenido a Firecrawl 🔥! Aquí tienes instrucciones para obtener el proyecto en local, ejecutarlo por tu cuenta y contribuir. Si vas a contribuir, ten en cuenta que el proceso es similar al de otros repositorios de código abierto: haz un fork de Firecrawl, realiza cambios, ejecuta las pruebas y abre un PR. Si tienes preguntas o necesitas ayuda para empezar, únete a nuestra comunidad de Discord aquí para más información o crea un issue en GitHub aquí.

Autohospedar Firecrawl

Consulta SELF_HOST.md para obtener instrucciones sobre cómo ejecutarlo localmente.

¿Por qué?

Alojar Firecrawl por tu cuenta es especialmente útil para organizaciones con políticas de seguridad estrictas que requieren mantener los datos en entornos controlados. Estas son algunas razones clave para considerar el autoalojamiento:
  • Mayor seguridad y cumplimiento: Al autoalojar, garantizas que el manejo y procesamiento de datos cumplan con normativas internas y externas, manteniendo la información sensible dentro de tu infraestructura segura. Ten en cuenta que Firecrawl es un producto de Mendable y cuenta con certificación SOC 2 Type II, lo que significa que la plataforma cumple con altos estándares del sector para la gestión de la seguridad de los datos.
  • Servicios personalizables: El autoalojamiento permite adaptar servicios como Playwright a necesidades específicas o a casos de uso particulares que quizá no estén cubiertos por la oferta estándar en la nube.
  • Aprendizaje y contribución a la comunidad: Al configurar y mantener tu propia instancia, obtienes una comprensión más profunda de cómo funciona Firecrawl, lo que también puede traducirse en contribuciones más valiosas al proyecto.

Consideraciones

Sin embargo, hay algunas limitaciones y responsabilidades adicionales que debes tener en cuenta:
  1. Acceso limitado a Fire-engine: Actualmente, las instancias autoalojadas de Firecrawl no tienen acceso a Fire-engine, que incluye funciones avanzadas para manejar bloqueos de IP, mecanismos de detección de bots y más. Esto significa que, aunque puedes gestionar tareas básicas de scraping, los escenarios más complejos podrían requerir configuración adicional o puede que no estén admitidos.
  2. Se requiere configuración manual: Si necesitas usar métodos de scraping más allá de las opciones básicas de fetch y Playwright, deberás configurarlos manualmente en el archivo .env. Esto requiere un conocimiento más profundo de las tecnologías y podría implicar más tiempo de configuración.
Autoalojar Firecrawl es ideal para quienes necesitan control total sobre sus entornos de scraping y procesamiento de datos, pero conlleva el coste de un mantenimiento y una configuración adicionales.

Pasos

  1. Primero, instala las dependencias
  1. Configura las variables de entorno
Crea un archivo .env en el directorio raíz; puedes copiar la plantilla desde apps/api/.env.example Para empezar, no configuraremos la autenticación ni ningún servicio opcional (análisis de PDF, bloqueo de JS, funciones de IA)
# .env

# ===== ENVS Requeridas ======
PORT=3002
HOST=0.0.0.0

# Nota: PORT es utilizado tanto por el servidor API principal como por el endpoint de verificación de actividad del worker

# Para activar la autenticación de BD, necesitas configurar Supabase.
USE_DB_AUTHENTICATION=false

# ===== ENVS Opcionales ======

## === Funcionalidades de IA (formato JSON en scrape, API /extract) ===
# Proporciona tu clave API de OpenAI aquí para habilitar las funcionalidades de IA
# OPENAI_API_KEY=

# Experimental: Usar Ollama
# OLLAMA_BASE_URL=http://localhost:11434/api
# MODEL_NAME=deepseek-r1:7b
# MODEL_EMBEDDING_NAME=nomic-embed-text

# Experimental: Usar cualquier API compatible con OpenAI
# OPENAI_BASE_URL=https://example.com/v1
# OPENAI_API_KEY=

## === Proxy ===
# PROXY_SERVER puede ser una URL completa (ej. http://0.1.2.3:1234) o solo una combinación de IP y puerto (ej. 0.1.2.3:1234)
# No descomentes PROXY_USERNAME y PROXY_PASSWORD si tu proxy no requiere autenticación
# PROXY_SERVER=
# PROXY_USERNAME=
# PROXY_PASSWORD=

## === API /search ===
# Por defecto, la API /search utilizará la búsqueda de Google.

# Puedes especificar un servidor SearXNG con el formato JSON habilitado, si prefieres usarlo en lugar de Google directo.
# También puedes personalizar los parámetros de engines y categories, pero los valores predeterminados también deberían funcionar bien.
# SEARXNG_ENDPOINT=http://your.searxng.server
# SEARXNG_ENGINES=
# SEARXNG_CATEGORIES=

## === Otros ===

# Configuración de Supabase (utilizado para soportar autenticación de BD, registro avanzado, etc.)
# SUPABASE_ANON_TOKEN=
# SUPABASE_URL=
# SUPABASE_SERVICE_TOKEN=

# Usa esto si has configurado autenticación y quieres probar con una clave API real
# TEST_API_KEY=

# Esta clave te permite acceder al panel de administración de colas. Cámbiala si tu despliegue es accesible públicamente.
BULL_AUTH_KEY=CHANGEME

# Esto ahora se autoconfigura mediante el docker-compose.yaml. No deberías necesitar configurarlo.
# PLAYWRIGHT_MICROSERVICE_URL=http://playwright-service:3000/scrape
# REDIS_URL=redis://redis:6379
# REDIS_RATE_LIMIT_URL=redis://redis:6379

# Configura esto si tienes una clave de llamaparse que te gustaría usar para analizar PDFs
# LLAMAPARSE_API_KEY=

# Configura esto si te gustaría enviar mensajes de estado de salud del servidor a Slack
# SLACK_WEBHOOK_URL=

# Configura esto si te gustaría enviar eventos de posthog como registros de trabajos
# POSTHOG_API_KEY=
# POSTHOG_HOST=

## === Configuración de Recursos del Sistema ===
# Umbral máximo de uso de CPU (0.0-1.0). El worker rechazará nuevos trabajos cuando el uso de CPU exceda este valor.
# Predeterminado: 0.8 (80%)
# MAX_CPU=0.8

# Umbral máximo de uso de RAM (0.0-1.0). El worker rechazará nuevos trabajos cuando el uso de memoria exceda este valor.
# Predeterminado: 0.8 (80%)
# MAX_RAM=0.8

# Configura esto si te gustaría permitir que se envíen webhooks locales a tu instancia autohospedada
# ALLOW_LOCAL_WEBHOOKS=true
  1. (Opcional) Ejecutar con el servicio de Playwright en TypeScript
    • Actualiza el archivo docker-compose.yml para cambiar el servicio de Playwright:
          build: apps/playwright-service
      
      A
          build: apps/playwright-service-ts
      
    • Define PLAYWRIGHT_MICROSERVICE_URL en tu archivo .env:
      PLAYWRIGHT_MICROSERVICE_URL=http://localhost:3000/scrape
      
    • No olvides configurar el servidor proxy en tu archivo .env según sea necesario.
  2. Compila y ejecuta los contenedores de Docker:
    docker compose build
    docker compose up
    
Esto iniciará una instancia local de Firecrawl accesible en http://localhost:3002. Deberías poder ver la interfaz de Bull Queue Manager en http://localhost:3002/admin/@/queues.
  1. (Opcional) Prueba la API
Si quieres probar el endpoint de crawl, puedes ejecutar lo siguiente:
  curl -X POST http://localhost:3002/v2/crawl \
      -H 'Content-Type: application/json' \
      -d '{
        "url": "https://docs.firecrawl.dev"
      }'

Solución de problemas

Esta sección ofrece soluciones a problemas comunes que puedes encontrar al configurar o ejecutar tu instancia autoalojada de Firecrawl.

El cliente de Supabase no está configurado

Síntoma:
[YYYY-MM-DDTHH:MM:SS.SSSz]ERROR - Se intentó acceder al cliente de Supabase cuando no está configurado.
[YYYY-MM-DDTHH:MM:SS.SSSz]ERROR - Error al insertar el evento de scraping: Error: el cliente de Supabase no está configurado.
Explicación: Este error ocurre porque la configuración del cliente de Supabase no está completa. Deberías poder hacer scraping y crawling sin problemas. Actualmente no es posible configurar Supabase en instancias autogestionadas.

Estás eludiendo la autenticación

Síntoma:
[YYYY-MM-DDTHH:MM:SS.SSSz]WARN - Estás eludiendo la autenticación
Explicación: Este error se debe a que la configuración del cliente de Supabase no está completa. Deberías poder realizar scraping y crawling sin problemas. Por ahora, no es posible configurar Supabase en instancias autogestionadas.

Los contenedores de Docker no arrancan

Síntoma: Los contenedores de Docker se detienen inesperadamente o no llegan a iniciarse. Solución: Consulta los registros de Docker para ver si hay mensajes de error usando el siguiente comando:
docker logs [nombre_del_contenedor]
  • Asegúrate de que todas las variables de entorno necesarias estén correctamente definidas en el archivo .env.
  • Verifica que todos los servicios de Docker definidos en docker-compose.yml estén correctamente configurados y que las imágenes necesarias estén disponibles.

Problemas de conexión con Redis

Síntoma: Errores al conectarse a Redis, como tiempos de espera o “Connection refused”. Solución:
  • Asegúrate de que el servicio de Redis esté en ejecución en tu entorno Docker.
  • Verifica que REDIS_URL y REDIS_RATE_LIMIT_URL en tu archivo .env apunten a la instancia correcta de Redis.
  • Revisa la configuración de red y las reglas del firewall que puedan bloquear la conexión al puerto de Redis.

El punto de conexión de la API no responde

Síntoma: Las solicitudes a la API de la instancia de Firecrawl se agotan por tiempo de espera o no devuelven respuesta. Solución:
  • Asegúrate de que el servicio de Firecrawl esté en ejecución comprobando el estado del contenedor de Docker.
  • Verifica que las variables PORT y HOST en tu archivo .env sean correctas y que ningún otro servicio esté usando el mismo puerto.
  • Revisa la configuración de red para garantizar que el host sea accesible desde el cliente que realiza la solicitud a la API.
Al resolver estos problemas comunes, podrás lograr una configuración y operación más fluidas de tu instancia autogestionada de Firecrawl.

Instalar Firecrawl en un clúster de Kubernetes (versión simple)

Consulta el examples/kubernetes-cluster-install/README.md para ver las instrucciones de instalación de Firecrawl en un clúster de Kubernetes.