Ejecución local

Configura Firecrawl en tu máquina local para desarrollo y colaboración.

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 [e-mail] 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.

1. Asegúrate de que Docker y Docker Compose estén instalados.
2. Copia .env.example a .env en el directorio apps/api/ y configura las variables según sea necesario.
3. 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