> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firecrawl.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Running Locally

> Set up Firecrawl on your local machine for development and contribution.

This guide walks you through running the Firecrawl API server on your local machine. Follow these steps to set up the development environment, start the services, and send your first request.

If you're contributing, the process follows standard open-source conventions: fork the repo, make changes, run tests, and open a pull request. For questions or help getting started, reach out to [help@firecrawl.com](mailto:help@firecrawl.com) or [submit an issue](https://github.com/mendableai/firecrawl/issues).

## Prerequisites

Install the following before proceeding:

| Dependency | Required | Install guide                                                                         |
| ---------- | -------- | ------------------------------------------------------------------------------------- |
| Node.js    | Yes      | [nodejs.org](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs)       |
| pnpm (v9+) | Yes      | [pnpm.io](https://pnpm.io/installation)                                               |
| Redis      | Yes      | [redis.io](https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/) |
| PostgreSQL | Yes      | Via Docker (see below) or installed directly                                          |
| Docker     | Optional | Required for the PostgreSQL container setup                                           |

## Set up the database

You need a PostgreSQL database initialized with the schema at `apps/nuq-postgres/nuq.sql`. The easiest approach is to use the Docker image inside `apps/nuq-postgres`.

With Docker running, build and start the container:

```bash theme={null}
docker build -t nuq-postgres apps/nuq-postgres
```

```bash theme={null}
docker run --name nuqdb \
  -e POSTGRES_PASSWORD=postgres \
  -p 5433:5432 \
  -v nuq-data:/var/lib/postgresql/data \
  -d nuq-postgres
```

## Configure environment variables

Copy the template to create your `.env` file in the `apps/api/` directory:

```bash theme={null}
cp apps/api/.env.example apps/api/.env
```

For a minimal local setup without authentication or optional sub-services (PDF parsing, JS blocking, AI features), use the following configuration:

```bash apps/api/.env theme={null}
# ===== Required =====
NUM_WORKERS_PER_QUEUE=8
PORT=3002
HOST=0.0.0.0
REDIS_URL=redis://localhost:6379
REDIS_RATE_LIMIT_URL=redis://localhost:6379

## To turn on DB authentication, you need to set up supabase.
USE_DB_AUTHENTICATION=false

## PostgreSQL connection for queuing — change if credentials, host, or DB differ
NUQ_DATABASE_URL=postgres://postgres:postgres@localhost:5433/postgres

# ===== Optional =====
# SUPABASE_ANON_TOKEN=
# SUPABASE_URL=
# SUPABASE_SERVICE_TOKEN=
# TEST_API_KEY=               # Set if you've configured authentication and want to test with a real API key
# OPENAI_API_KEY=             # Required for LLM-dependent features (image alt generation, etc.)
# BULL_AUTH_KEY=@
# PLAYWRIGHT_MICROSERVICE_URL= # Set to run a Playwright fallback
# LLAMAPARSE_API_KEY=         # Set to parse PDFs with LlamaParse
# SLACK_WEBHOOK_URL=          # Set to send Slack server health status messages
# POSTHOG_API_KEY=            # Set to send PostHog events like job logs
# POSTHOG_HOST=               # Set to send PostHog events like job logs
```

## Install dependencies

From the `apps/api/` directory, install packages with pnpm:

```bash theme={null}
cd apps/api
pnpm install
```

## Start the services

You need three terminal sessions running simultaneously: Redis, the API server, and a terminal for sending requests.

### Terminal 1 — Redis

Start the Redis server from anywhere in the project:

```bash theme={null}
redis-server
```

### Terminal 2 — API server

Navigate to `apps/api/` and start the service:

```bash theme={null}
pnpm start
```

This starts the API server and the workers responsible for processing crawl jobs.

<Note>
  If you plan to use the [LLM extract feature](https://github.com/firecrawl/firecrawl/pull/586/), export your OpenAI key first: `export OPENAI_API_KEY=sk-...`
</Note>

### Terminal 3 — Send a test request

Verify the server is running with a health check:

```bash theme={null}
curl -X GET http://localhost:3002/test
```

This should return `Hello, world!`.

To test the crawl endpoint:

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

## Alternative: Docker Compose

For a simpler setup, Docker Compose runs all services (Redis, API server, and workers) in a single command.

1. Make sure Docker and Docker Compose are installed.
2. Copy `.env.example` to `.env` in the `apps/api/` directory and configure as needed.
3. From the project root, run:

```bash theme={null}
docker compose up
```

This starts all services automatically in the correct configuration.

## Running tests

Run the test suite with:

```bash theme={null}
npm run test:snips
```