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 [email protected] o abre un issue.

Instala lo siguiente antes de continuar:

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

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:

# ===== 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

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

cd apps/api
pnpm install

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

Inicia el servidor de Redis desde cualquier parte del proyecto:

redis-server

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.

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"
  }'

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.

Ejecuta la suite de pruebas con:

npm run test:snips