Skip to main content
Autoaloja Firecrawl con Docker Compose cuando necesites controlar el código fuente o la infraestructura. Esta guía fija la versión v2.11.162, inicia la API en http://localhost:3002 y verifica una respuesta correcta de POST /v2/scrape con Markdown.
Este inicio rápido para una red de confianza deshabilita la autenticación de la API y no es una arquitectura de producción. Se inicia sin almacenamiento persistente, TLS, alta disponibilidad ni todas las capacidades de Firecrawl Cloud.

​
Selecciona entre el autoalojamiento y Firecrawl Cloud

​
Autoalojar Firecrawl cuando

  • Quieres tener control sobre el código fuente o la infraestructura. Esta guía pone en marcha la API y sus servicios auxiliares en tu máquina.
  • Te sientes cómodo operando la pila. Te encargarás de las actualizaciones, la seguridad, el almacenamiento, la supervisión y la recuperación.
  • Quieres validar Firecrawl en tu entorno. Primero, pon en marcha la configuración base y luego diseña los controles descritos en Antes de producción.
Selecciona Firecrawl Cloud si quieres empezar a hacer scraping sin tener que operar infraestructura. Consulta Open Source vs Cloud para conocer las diferencias de funcionalidades. Nuestra recomendación: autoaloja Firecrawl si el acceso al código fuente o el control de la infraestructura compensan el trabajo operativo. Si buscas la vía más rápida y compatible para llegar a producción, empieza con Firecrawl Cloud.

​
Qué implica el autoalojamiento

  • Usted se encarga de las actualizaciones, los secretos, el almacenamiento, la supervisión, la recuperación y la respuesta ante incidentes.
  • El scraping sigue enviando solicitudes salientes a los sitios web objetivo. Los proveedores opcionales de proxy, parsing o IA añaden más flujos de datos.
  • Esta guía simplifica intencionadamente la primera ejecución. Haga funcionar un scraping y, después, cambie una decisión cada vez.
  • Los comandos están fijados a v2.11.162. Otra versión puede usar un contrato de Compose diferente.

​
Autoalojar Firecrawl con Docker Compose

​
Empieza con estos valores predeterminados

  • Versión: Firecrawl v2.11.162. Fija primero el código y la configuración. Actualiza después de revisar el archivo docker-compose.yaml y las notas de autoalojamiento de la versión de destino.
  • Autenticación de la API: desactivada para esta ejecución local. Añádela solo si cuentas con un diseño completo y compatible de identidad y base de datos; una sola variable de entorno no es suficiente.
  • Cola: PostgreSQL. Mantenla salvo que quieras operar deliberadamente el backend opcional de FoundationDB.
  • Interfaz de usuario de administración de la cola: desactivada. Habilítala solo con una BULL_AUTH_KEY robusta y controles de red.
  • Proveedores de IA y scraping avanzado: no configurados. Añade un proveedor cuando lo requiera alguna capacidad que necesites.
Mantén la primera ejecución simple: haz que funcione un scraping y luego añade lo que necesite tu caso de uso.

​
Requisitos previos

Antes de empezar, instala:
  • Git
  • Docker Engine o Docker Desktop
  • Docker Compose v2, invocado como docker compose
  • curl para las solicitudes de verificación
Asegúrate de que el puerto 3002 esté disponible y de que Docker tenga capacidad suficiente para compilar y ejecutar varios servicios. Firecrawl no publica requisitos mínimos verificados para el host de esta pila.

​
Clona la versión verificada

Esta guía se verificó con Firecrawl v2.11.162. Obtén exactamente esa versión para mantener sincronizados el código, los comandos y la configuración:
¿Quieres usar otra versión? Consulta su docker-compose.yaml y las notas sobre autoalojamiento antes de reutilizar estos valores.

​
Configura el entorno de evaluación

Crea el archivo .env mínimo funcional en la raíz del repositorio:
Cambia la contraseña de PostgreSQL antes de iniciar la pila y no subas .env al repositorio. Mantén POSTGRES_DB=postgres para v2.11.162, ya que la configuración incluida de pg_cron apunta a esa base de datos. Compose pasa estos valores tanto a la API como al servicio de PostgreSQL.
apps/api/.env.example es para el desarrollo de la API, no es un archivo de Compose listo para usar. Esta primera ejecución deshabilita la autenticación de la base de datos, por lo que las solicitudes no necesitan una clave de API ni una cabecera Authorization.
Deja NUQ_BACKEND y BULL_AUTH_KEY sin configurar. Usarás la cola de PostgreSQL sin ejecutar la interfaz de usuario de administración de colas: menos componentes que gestionar en el primer scraping.

​
Compila e inicia Firecrawl

Compila el código fuente clonado e inicia todo en segundo plano:
Es normal que aparezcan advertencias sobre variables opcionales sin configurar en esta configuración de referencia. docker compose ps --all debería mostrar la API y los servicios auxiliares en ejecución, con los servicios de inicialización de ejecución única completados. Espere un poco si los servicios todavía se están iniciando.

​
Comprueba que la API sea accesible

Primero, asegúrate de que la API pueda responder a una solicitud HTTP:
Respuesta esperada:
Esto es una comprobación de actividad, no una prueba integral. No comprueba Redis, PostgreSQL, RabbitMQ, Playwright, los workers ni el acceso saliente a la red. Ejecute el scraping a continuación antes de considerar que el despliegue está listo para usarse.

​
Realiza una prueba rápida de funcionamiento

Ahora prueba lo importante: un scraping real. El tiempo de espera de la solicitud se indica en milisegundos; el del cliente curl, en segundos, y es ligeramente mayor:
Una respuesta correcta tiene esta estructura:
Esto comprueba conjuntamente la API, el pipeline de scraping, una ruta del motor de scraping y el acceso saliente. Los metadatos exactos pueden variar según la respuesta del objetivo. Si obtiene estos campos de éxito, Firecrawl funciona de extremo a extremo en su infraestructura. Conserve esta referencia y seleccione qué añadir a continuación.

​
Compatibilidad de funciones autogestionadas

Tu primer scraping funciona. Añade la siguiente capacidad porque la necesitas, no solo porque exista: Para una comparación más amplia del producto, consulta Open Source vs Cloud. Para la configuración específica de cada versión, usa como referencia complementaria el archivo docker-compose.yaml fijado.

​
Antes de pasar a producción

Compose permite lograr el primer resultado. Antes de exponer la API fuera de una red de confianza, el entorno de producción requiere algunas decisiones explícitas:
  • Si los datos deben sobrevivir al reemplazo de servicios, añade almacenamiento persistente para PostgreSQL, Redis y RabbitMQ, y define y prueba procedimientos de copia de seguridad y restauración. El archivo Compose proporcionado no añade esos volúmenes.
  • Si usuarios o redes no confiables pueden acceder a la API, implementa un diseño de autenticación compatible, controles de acceso a la red y TLS en un proxy inverso o ingress. No expongas públicamente esta configuración base sin autenticación.
  • Si tienes requisitos de disponibilidad o capacidad, define objetivos de disponibilidad, supervisión, dimensionamiento de recursos, criterios de escalado y procedimientos de actualización y reversión. Los límites de Compose no son requisitos mínimos validados.
  • Si la ubicación de los datos o el cumplimiento normativo son importantes, relaciona las solicitudes con los sitios web objetivo y con cada proveedor opcional de IA, proxy o parsing antes de habilitarlos.
  • Si los secretos deben gestionarse de forma centralizada, mueve la contraseña de la base de datos de .env al sistema de gestión de secretos de tu plataforma.
Estas son decisiones de infraestructura. No existe una única opción en .env que prepare la pila para producción.

​
Próximos pasos

  • ¿Aún estás evaluando? Mantén la API en una red de confianza y ejecuta docker compose down cuando termines.
  • ¿Vas a añadir una funcionalidad de código abierto? Usa Compatibilidad de funciones autogestionadas para encontrar el proveedor o servicio necesario y, después, prueba esa ruta por separado.
  • ¿Vas a modificar el código de Firecrawl? Consulta Ejecución local para configurar el entorno de desarrollo para colaboradores.
  • ¿Vas a conectar un cliente? Configura la CLI de Firecrawl o el servidor MCP local para que apunten a la URL verificada de tu API.
  • ¿Vas a migrar a Kubernetes? Comienza con las referencias versionadas de Kubernetes o Helm enlazadas desde SELF_HOST.md y, después, deja explícitas las decisiones de producción anteriores para tu plataforma.
  • ¿Quieres infraestructura gestionada o funcionalidades exclusivas de Cloud? Compara Open Source vs Cloud.
  • ¿Vas a pasar a producción? Completa todas las decisiones de Antes de producción antes de exponer la API.

​
Resolución de problemas

​
Estás omitiendo la autenticación

Si ves esta advertencia con USE_DB_AUTHENTICATION=false, estás siguiendo el flujo esperado de la primera ejecución. Las solicitudes usan una identidad autogestionada y no requieren una clave de API. Si se puede acceder a la API desde una red no confiable, detente y añade los controles indicados en Antes de producción.

​
Los contenedores de Docker no se inician

Si algún servicio de larga duración se detiene, inspecciona el estado del contenedor y los registros recientes:
  • Si la revisión de origen es distinta, haz checkout de v2.11.162 o usa la configuración de esa versión.
  • Si los recursos disponibles para una compilación o un contenedor son limitados, aumenta la capacidad de CPU, memoria o disco de Docker.
  • Si PostgreSQL falla, revisa la sintaxis de .env, mantén POSTGRES_DB=postgres y asegúrate de que los valores de usuario y contraseña coincidan.

​
Problemas de conexión con Redis

Si un contenedor no puede conectarse a Redis, usa la dirección del servicio de Compose redis://redis:6379. localhost apunta al propio contenedor, no al servicio de Redis.
Si añadiste REDIS_URL o REDIS_RATE_LIMIT_URL, elimina la configuración que la anula para restaurar el valor predeterminado o usa una dirección accesible desde la red de Compose.

​
El endpoint de la API no responde

Si el puerto 3002 no responde, revisa el contenedor de la API y sus registros:
Si otro proceso está usando el puerto 3002, detenlo o cambia el puerto publicado de forma coherente. Durante el inicio, vuelve a intentarlo solo cuando el contenedor de la API aparezca como en ejecución. Si /v0/health/readiness responde correctamente, pero /v2/scrape falla, revisa los registros de la API y de Playwright, ya que el endpoint de disponibilidad no valida esas dependencias:

​
La solicitud de scraping supera el tiempo de espera

Si el scraping supera el tiempo de espera, confirma que la implementación puede acceder a https://example.com y que los servicios de la API y Playwright están en ejecución. Mantén el valor de --max-time de curl por encima del timeout del cuerpo de la solicitud para que la API pueda devolver su propia respuesta de tiempo de espera.