Self-hosting Firecrawl
with Docker.

We ran every step below on 1 November 2026, on release v2.11.162, the release Firecrawl's self-hosting docs pin. The test machine was a Fedora 44 desktop with 24 CPU threads and 62 GB of RAM, running Docker 29.9 and Compose 5.6. The commands come from Firecrawl's docs, SELF_HOST.md and the docker-compose.yaml. The timings, memory figures and outputs are from our run.

What the self-hosted stack runs

Firecrawl is licensed under AGPL-3.0. You can run it unmodified for yourself. If you change the code and offer it to other people over a network, the AGPL requires you to publish your changes.

The root Compose file defines these services:

• api: the Firecrawl API and its workers in one container. It is the only service published to the host, on port 3002. Compose caps it at 4 CPUs and 8 GB of memory.
• playwright-service: a headless browser for pages that need JavaScript. Capped at 2 CPUs and 4 GB.
• redis: Redis, which the API also uses for rate limiting.
• rabbitmq: RabbitMQ, which the job queue connects to.
• nuq-postgres: PostgreSQL, which holds the default job queue.
• foundationdb and foundationdb-init: an experimental queue backend, used only if you set NUQ_BACKEND=fdb.

Firecrawl says the Compose limits are not verified minimums, and it publishes no minimum host size. The two caps add up to 6 CPUs and 12 GB. A third-party guide on Ubuntu gives 8 GB of RAM and 4 cores as a minimum. In our test, after a 20-page crawl and a few scrapes, the whole stack used about 3.4 GB: 2.9 GB for the API container, 210 MB for Playwright and under 200 MB each for RabbitMQ, PostgreSQL, Redis and FoundationDB. That was a light load. We suggest a 16 GB server for steady use, so both caps fit with room for the other services, but check it against your own load.

Setup in five steps

You need Git, Docker Engine or Docker Desktop, Docker Compose v2 (run as docker compose) and curl. Port 3002 must be free.

1. Clone the repository and pin the release

$ git clone https://github.com/firecrawl/firecrawl.git
$ cd firecrawl
$ git checkout v2.11.162

The docs say to check out an exact tag. The main branch and the floating image tags can change separately, and GitHub issues show what happens when they do. In issue #2111, the API container stopped starting after new images were pulled. In issue #2551, a fresh build of main crashed on launch with a missing database relation.

2. Create the .env file

Put this file in the repository root, next to docker-compose.yaml:

$ cat > .env <<'EOF'
USE_DB_AUTHENTICATION=false
POSTGRES_USER=postgres
POSTGRES_PASSWORD=replace-with-at-least-32-random-characters
POSTGRES_DB=postgres
EOF

• Replace the password before you start the stack, and don't commit .env.
• Keep POSTGRES_DB=postgres. In v2.11.162, the bundled pg_cron configuration targets that database.
• Leave NUQ_BACKEND and BULL_AUTH_KEY unset for the first run.
• Don't copy apps/api/.env.example instead. Older guides do, but the docs say that file is for API development and is not a Compose file. The root .env only sets variables that docker-compose.yaml reads.

3. Build and start the stack

$ docker compose up --build -d
$ docker compose ps --all

The Compose file builds every Firecrawl image from source by default. On our machine the build took 13 minutes and produced three images: firecrawl-api (1.5 GB), firecrawl-playwright-service (2.1 GB) and firecrawl-nuq-postgres (640 MB). Our first attempt stopped after 35 seconds with connection reset by peer while it was downloading a base image. Running the same command again finished without errors, so retry if the network drops.

Compose prints about 30 warnings that optional variables such as OPENAI_API_KEY and PROXY_SERVER are not set. They are expected. docker compose ps --all should then show this:

SERVICE              STATUS
api                  Up 5 seconds
foundationdb         Up 10 seconds
foundationdb-init    Exited (0) 1 second ago
nuq-postgres         Up 10 seconds
playwright-service   Up 10 seconds
rabbitmq             Up 10 seconds (healthy)
redis                Up 10 seconds

foundationdb-init is a one-shot job, so Exited (0) is correct. In the API logs, one worker reported a RabbitMQ noproc error at startup and then logged "falling back to postgres". Every test below still passed, so that error alone doesn't mean the stack is broken.

To skip the build, comment out each build: line and uncomment the image: line under it. The prebuilt images are ghcr.io/firecrawl/firecrawl, ghcr.io/firecrawl/playwright-service:latest and ghcr.io/firecrawl/nuq-postgres:latest. Those tags float, so they may not match the v2.11.162 checkout.

4. Check that the API answers

$ curl --fail --silent --show-error --max-time 5 \
    http://localhost:3002/v0/health/readiness
{"status":"ok"}

Our first check, sent right after docker compose up returned, failed with Connection reset by peer because the API was still starting. A few seconds later it returned {"status":"ok"}. This is only a heartbeat. It does not check Redis, PostgreSQL, RabbitMQ, Playwright, the workers or outbound network access.

5. Run one real scrape

$ curl --fail-with-body --silent --show-error --max-time 75 \
    -X POST http://localhost:3002/v2/scrape \
    -H 'Content-Type: application/json' \
    -d '{"url": "https://example.com", "formats": ["markdown"], "timeout": 60000}'

A working stack returns "success": true with data.markdown and data.metadata.statusCode. The timeout in the body is in milliseconds, and curl's --max-time is in seconds. Keep curl's limit longer, so the API can return its own timeout error. No API key or Authorization header is needed, because authentication is off. Our first scrape of example.com returned "success": true and status code 200 in 1.4 seconds. A second run took 0.7 seconds.

What worked in our test

With the default .env and no LLM, proxy or SearXNG settings, we sent these requests to the stack:

Scrape, crawl and search worked out of the box, and Playwright handled the JavaScript page. Map depends on what it can discover: it found 1,486 URLs on a docs site with a sitemap and none on a small site that has no sitemap. The screenshot request returned "success": true but no screenshot, so check for a warning field rather than trusting success alone.

Adding AI features, proxies and search

The docs say to get one scrape working first and then add one thing at a time. The Compose file passes these variables through:

• For LLM features such as JSON extraction, set OPENAI_API_KEY, OPENAI_BASE_URL, MODEL_NAME and MODEL_EMBEDDING_NAME, or OLLAMA_BASE_URL for a local model. Any OpenAI-compatible endpoint works through OPENAI_BASE_URL. We set OPENAI_BASE_URL=https://openrouter.ai/api/v1, an OpenRouter key and MODEL_NAME=openai/gpt-4o-mini, restarted the API with docker compose up -d api, and JSON extraction worked. We left MODEL_EMBEDDING_NAME unset for that test. The restart took 9 seconds.
• For proxies, set PROXY_SERVER, PROXY_USERNAME and PROXY_PASSWORD, which go to both the API and the Playwright service. BLOCK_MEDIA stops Playwright loading media, which saves proxy bandwidth.
• For search, set SEARXNG_ENDPOINT, plus the optional SEARXNG_ENGINES and SEARXNG_CATEGORIES.
• Throughput is controlled by NUM_WORKERS_PER_QUEUE (default 8), CRAWL_CONCURRENT_REQUESTS (10), MAX_CONCURRENT_JOBS (5) and BROWSER_POOL_SIZE (5).

In the v2.11.162 source, /search uses Fire-engine if FIRE_ENGINE_BETA_URL is set. Without Fire-engine it uses SearXNG if SEARXNG_ENDPOINT is set, and otherwise it falls back to DuckDuckGo. If a search errors, the function returns an empty list, so your client gets no results and no error message. To choose the search engines yourself, run your own SearXNG instance. Our SearXNG Docker Compose guide shows how to connect it to Firecrawl's api service.

What self-hosting leaves out

Firecrawl's docs list these differences between the self-hosted build and Firecrawl Cloud:

Without Fire-engine, pages load through plain fetch or the bundled Playwright browser, so sites with strong bot protection may return errors or empty pages. Issue #2350 describes workers stuck in a loop of "Waterfalling to next engine..." messages on pages that blocked them. Your own proxies help with rate limits, but a proxy does not guarantee access to a site.

Before you expose it to the internet

The docs call the setup above a trusted-network quickstart. Five things are missing for production:

• Authentication. With USE_DB_AUTHENTICATION=false, anyone who reaches port 3002 can use your server. The docs say switching that variable on is not enough by itself, because authentication also needs a database schema and application setup.
• TLS and network rules. Put TLS on a reverse proxy or ingress, and keep the PostgreSQL, Redis, RabbitMQ and worker ports private.
• Persistent storage. The Compose file defines no volumes for PostgreSQL, Redis or RabbitMQ, so their data is lost when a container is replaced. Add volumes and test a backup and restore.
• Secrets. Move the database password from .env into a secret manager.
• Admin routes. Setting BULL_AUTH_KEY turns on admin routes, including a queue UI. Setting ADMIN_INTERNAL_PORT starts a second listener that needs no key, so never publish that port.

For Kubernetes, SELF_HOST.md links Kubernetes manifests and a Helm chart in the repository. Firecrawl calls them versioned starting points, not finished production setups.

Cost: a server vs Firecrawl Cloud

The self-hosted software is free. You pay for the server, any proxies, any LLM tokens, and the time spent running it. Firecrawl Cloud charges a monthly plan that includes credits. A scraped or crawled page costs 1 credit, a search costs 2 credits per 10 results, and the JSON format adds 4 credits per page.

Two examples of a 16 GB server, the size we suggest above:

• DigitalOcean Basic droplet, 8 vCPUs and 16 GiB: $96 a month. The 8 GiB, 4 vCPU droplet is $48.
• Hetzner CX43, 8 vCPUs and 16 GB, in Germany or Finland: €16.49 a month before VAT. The 8 GB CX33 is €8.99. Hetzner's page marked these plans as currently unavailable when we checked.

Proxies, LLM tokens for extraction, and the time to patch, upgrade and debug the stack all come on top of the server price. In our view, at a few thousand pages a month the Free or Hobby plan costs less than the time it takes to maintain a server. Self-hosting pays off at high volume on easy sites, or when the data must stay on your own infrastructure.

Troubleshooting

The docs and the most-commented self-host issues on GitHub cover these problems:

• A container exits on start. Run docker compose ps --all and docker compose logs --tail=200. Check that you are on v2.11.162, that Docker has enough CPU, memory and disk, and that the .env values are consistent.
• "Port 3002 did not become available". On slow machines the API took longer to start than the startup timeout (issue #2366). The default is now 60 seconds, and you can raise it with HARNESS_STARTUP_TIMEOUT_MS, for example 120000.
• Redis connection errors. Inside Compose, use redis://redis:6379. localhost points to the container itself, not to Redis. Remove any REDIS_URL or REDIS_RATE_LIMIT_URL override.
• A RabbitMQ noproc error at startup. We saw it once, followed by "falling back to postgres". The stack kept working. If scrapes fail as well, check that the rabbitmq service shows as healthy.
• JSON extraction returns HTTP 500. The response only says "An error occurred" with an error ID. Search the API logs for that ID. In our test the log said Failed to parse URL from /responses, which means no LLM provider was set. Set OPENAI_API_KEY and OPENAI_BASE_URL, or OLLAMA_BASE_URL.
• Map returns 0 URLs. We saw this on a small site that has no sitemap, while a site with a sitemap returned 1,486 URLs. Use /v2/crawl with a page limit to discover links on such sites.
• Readiness works but scrapes fail. Read docker compose logs --tail=200 api playwright-service. The readiness check does not test Playwright or the workers.
• Scrapes time out. Check that the server can reach https://example.com and that the API and Playwright are running.
• Memory keeps growing. Issue #722 reported memory on a 2-core, 4 GB server rising from 13% to 85% during crawls and staying there until a restart. A fix was merged later. The Ubuntu guide also hit exit code 137, which means the kernel killed a container for using too much memory.
• Errors after an upgrade. Run docker compose down before you rebuild, so old containers don't run against the new images (the maintainers' advice in issue #2551).

Running Fireplexity on self-hosted Firecrawl

Fireplexity, the open-source answer engine this site covers, calls Firecrawl's /v2/search endpoint. It can use a self-hosted Firecrawl after a one-line change to the API address. The self-hosted search returns web results only, so Fireplexity's news and image panels stay empty. Our self-hosting guide covers that change and a fully local setup with Ollama. If you would rather not run Firecrawl at all, our Firecrawl alternatives page compares hosted and self-hosted replacements.

Common questions