Self-hosting Firecrawl

​

Choose self-hosting or Firecrawl Cloud

​

Self-host Firecrawl when

• You want control over the source or infrastructure. This guide gets the API and its supporting services running on your machine.
• You are comfortable operating the stack. You will own upgrades, security, storage, monitoring, and recovery.
• You want to validate Firecrawl against your environment. Get the baseline working here, then design the controls in Before production.

​

What self-hosting requires

• You own upgrades, secrets, storage, monitoring, recovery, and incident response.
• Scraping still sends outbound requests to target websites. Optional proxy, parsing, or AI providers add more data flows.
• This guide keeps the first run intentionally simple. Get one scrape working, then change one decision at a time.
• The commands are pinned to v2.11.162. A different release may use a different Compose contract.

​

Self-host Firecrawl with Docker Compose

​

Start with these defaults

• Release: Firecrawl v2.11.162. Pin the code and configuration first. Upgrade after reviewing the target release’s docker-compose.yaml and self-hosting notes.
• API authentication: off for this local run. Add it only with a complete supported identity and database design; one environment variable is not enough.
• Queue: PostgreSQL. Keep it unless you intentionally want to operate the optional FoundationDB backend.
• Queue admin UI: off. Enable it only with a strong BULL_AUTH_KEY and network controls.
• AI and advanced scraping providers: not configured. Add a provider when a capability you need requires it.

​

Prerequisites

• Git
• Docker Engine or Docker Desktop
• Docker Compose v2, invoked as docker compose
• curl for the verification requests

​

Clone the verified release

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

​

Configure the evaluation deployment

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

​

Build and start Firecrawl

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

​

Check API reachability

curl \
  --fail \
  --silent \
  --show-error \
  --max-time 5 \
  http://localhost:3002/v0/health/readiness

{"status":"ok"}

​

Run a functional smoke test

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

{
  "success": true,
  "data": {
    "markdown": "...",
    "metadata": {
      "statusCode": 200
    }
  }
}

​

Self-hosted feature support

​

Before production

• If data must survive service replacement, add durable storage for PostgreSQL, Redis, and RabbitMQ, then define and test backup and restore procedures. The provided Compose file does not add those volumes.
• If users or untrusted networks can reach the API, add a supported authentication design, network access controls, and TLS at a reverse proxy or ingress. Do not expose this unauthenticated baseline publicly.
• If you have availability or capacity requirements, set uptime targets, monitoring, resource sizing, scaling triggers, and upgrade and rollback procedures. The Compose limits are not verified minimum requirements.
• If data location or compliance matters, map requests to target websites and every optional AI, proxy, or parsing provider before enabling them.
• If secrets must be managed centrally, move the database password out of .env and into your platform’s secret-management system.

​

Where to go next

• Still evaluating? Keep the API on a trusted network and run docker compose down when you are finished.
• Adding an open-source capability? Use Self-hosted feature support to find the required provider or service, then test that path on its own.
• Changing Firecrawl code? Switch to Running Locally for the contributor development environment.
• Connecting a client? Point the Firecrawl CLI or local MCP server at your verified API URL.
• Moving to Kubernetes? Start with the versioned Kubernetes or Helm references linked from SELF_HOST.md, then make the production decisions above explicit for your platform.
• Want managed infrastructure or Cloud-only capabilities? Compare Open Source vs Cloud.
• Going to production? Complete every decision in Before production before exposing the API.

​

Troubleshooting

​

You’re bypassing authentication

​

Docker containers fail to start

docker compose ps --all
docker compose logs --tail=200

• If the source revision differs, either check out v2.11.162 or use that release’s configuration.
• If a build or container is resource-constrained, increase Docker CPU, memory, or disk capacity.
• If PostgreSQL fails, check .env syntax, keep POSTGRES_DB=postgres, and make sure the user and password values are consistent.

​

Connection issues with Redis

docker compose ps redis
docker compose logs --tail=100 redis

​

API endpoint does not respond

docker compose ps api
docker compose logs --tail=200 api

docker compose logs --tail=200 api playwright-service

​

Scrape request times out