Ejecución local

Esta guía te explica cómo ejecutar el servidor de la API de Firecrawl en tu máquina local. Sigue estos pasos para configurar el entorno de desarrollo, iniciar los servicios y enviar tu primera solicitud. Si vas a contribuir, el proceso sigue las convenciones estándar de código abierto: haz un fork del repositorio, realiza cambios, ejecuta las pruebas y abre un pull request. Si tienes dudas o necesitas ayuda para comenzar, escribe a help@firecrawl.com o abre un issue.

Requisitos previos

Instala lo siguiente antes de continuar:

Dependencia	Obligatorio	Guía de instalación
Node.js	Sí	nodejs.org
pnpm (v9+)	Sí	pnpm.io
Redis	Sí	redis.io
PostgreSQL	Sí	Mediante Docker (ver más abajo) o instalado directamente
Docker	Opcional	Necesario para la configuración del contenedor de PostgreSQL

Configura la base de datos

Necesitas una base de datos PostgreSQL inicializada con el esquema en apps/nuq-postgres/nuq.sql. La forma más sencilla es usar la imagen de Docker dentro de apps/nuq-postgres. Con Docker en ejecución, construye y arranca el contenedor:

docker build -t nuq-postgres apps/nuq-postgres

docker run --name nuqdb \
  -e POSTGRES_PASSWORD=postgres \
  -p 5433:5432 \
  -v nuq-data:/var/lib/postgresql/data \
  -d nuq-postgres

Configurar variables de entorno

Copia la plantilla para crear el archivo .env en el directorio apps/api/:

cp apps/api/.env.example apps/api/.env

Para una configuración local mínima sin autenticación ni servicios opcionales (análisis de PDF, bloqueo de JS, funciones de IA), usa la siguiente configuración:

apps/api/.env

# ===== Requerido =====
NUM_WORKERS_PER_QUEUE=8
PORT=3002
HOST=0.0.0.0
REDIS_URL=redis://localhost:6379
REDIS_RATE_LIMIT_URL=redis://localhost:6379

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

## Conexión PostgreSQL para colas — cambia si las credenciales, el host o la BD difieren
NUQ_DATABASE_URL=postgres://postgres:postgres@localhost:5433/postgres

# ===== Opcional =====
# SUPABASE_ANON_TOKEN=
# SUPABASE_URL=
# SUPABASE_SERVICE_TOKEN=
# TEST_API_KEY=               # Configura si habilitaste autenticación y quieres probar con una clave API real
# OPENAI_API_KEY=             # Necesario para funciones que dependen de LLM (generación de texto alternativo de imágenes, etc.)
# BULL_AUTH_KEY=@
# PLAYWRIGHT_MICROSERVICE_URL= # Configura para ejecutar un fallback de Playwright
# LLAMAPARSE_API_KEY=         # Configura para procesar PDFs con LlamaParse
# SLACK_WEBHOOK_URL=          # Configura para enviar mensajes de estado del servidor a Slack
# POSTHOG_API_KEY=            # Configura para enviar eventos de PostHog como registros de trabajos
# POSTHOG_HOST=               # Configura para enviar eventos de PostHog como registros de trabajos

Instala las dependencias

Desde el directorio apps/api/, instala los paquetes con pnpm:

cd apps/api
pnpm install

Inicia los servicios

Necesitas tres sesiones de terminal en ejecución simultánea: Redis, el servidor de la API y otra terminal para enviar solicitudes.

Terminal 1 — Redis

Inicia el servidor de Redis desde cualquier parte del proyecto:

redis-server

Terminal 2 — Servidor de la API

Ve a apps/api/ y inicia el servicio:

pnpm start

Esto inicia el servidor de la API y los workers encargados de procesar las tareas de rastreo.

Si planeas usar la función de extracción mediante LLM, primero exporta tu clave de OpenAI: export OPENAI_API_KEY=sk-...

Terminal 3 — Enviar una petición de prueba

Verifica que el servidor esté en ejecución mediante una comprobación de estado (health check):

curl -X GET http://localhost:3002/test

Esto debería devolver Hello, world!. Para probar el endpoint de rastreo:

curl -X POST http://localhost:3002/v1/crawl \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://mendable.ai"
  }'

Alternativa: Docker Compose

Para una configuración más sencilla, Docker Compose ejecuta todos los servicios (Redis, servidor de la API y workers) con un solo comando.

Asegúrate de que Docker y Docker Compose estén instalados.
Copia .env.example a .env en el directorio apps/api/ y configura las variables según sea necesario.
Desde la raíz del proyecto, ejecuta:

docker compose up

Esto inicia todos los servicios automáticamente en la configuración adecuada.

Ejecutar pruebas

Ejecuta la suite de pruebas con:

npm run test:snips

Primeros pasos

Endpoints principales

Más

Inicios rápidos

Guías para desarrolladores

Webhooks

Casos de uso

Otros

Contribuciones

Requisitos previos

Configura la base de datos

Configurar variables de entorno

Instala las dependencias

Inicia los servicios

Terminal 1 — Redis

Terminal 2 — Servidor de la API

Terminal 3 — Enviar una petición de prueba

Alternativa: Docker Compose

Ejecutar pruebas

​Requisitos previos

​Configura la base de datos

​Configurar variables de entorno

​Instala las dependencias

​Inicia los servicios

​Terminal 1 — Redis

​Terminal 2 — Servidor de la API

​Terminal 3 — Enviar una petición de prueba

​Alternativa: Docker Compose

​Ejecutar pruebas

Requisitos previos

Configura la base de datos

Configurar variables de entorno

Instala las dependencias

Inicia los servicios

Terminal 1 — Redis

Terminal 2 — Servidor de la API

Terminal 3 — Enviar una petición de prueba

Alternativa: Docker Compose

Ejecutar pruebas