Lesson 3 — Self-Hosting Firecrawl

⏱ Est. reading time: 4 min Updated on 5/7/2026

Self-hosting is the best choice when you have high-volume scraping needs or sensitive data requirements.

3.1 Option A: Docker Deployment (Recommended)

This is the simplest and most stable method, as all dependencies run inside containers.

1. Clone the Repository and Configure

git clone https://github.com/firecrawl/firecrawl.git
cd firecrawl
cp apps/api/.env.example apps/api/.env

2. Minimal Environment Configuration

Edit apps/api/.env and ensure the following are set:

  • USE_DB_AUTHENTICATION=false (Usually disabled for local use)
  • PORT=3002

3. Start the Services

docker compose up

This starts Redis, PostgreSQL, the API Server, and Workers. Visit http://localhost:3002/test; if you see "Hello, world!", the setup was successful.

3.2 Option B: Source Compilation

Use this method if you need to modify the code or perform deep debugging.

Prerequisites:

  • Node.js 18+ & pnpm
  • Redis 7+ (Task queue)
  • PostgreSQL 15+ (Data storage)

Core Steps:

  1. Database Initialization: Build and start the database with the schema using the Dockerfile in apps/nuq-postgres.
  2. Install Dependencies: Run pnpm install in the root directory.
  3. Environment Variables: Same as the Docker method, but point REDIS_URL and DATABASE_URL to your local instances.
  4. Start: Run pnpm start in the apps/api directory.

3.3 Configuring Local MCP Connection

To use your self-hosted Firecrawl in Claude Code, adjust your configuration:

{
  "mcpServers": {
    "firecrawl-local": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_URL": "http://localhost:3002",
        "FIRECRAWL_API_KEY": "" 
      }
    }
  }
}

Note: In local mode, if USE_DB_AUTHENTICATION is disabled, the FIRECRAWL_API_KEY can be left empty.

3.4 Troubleshooting

  • ECONNREFUSED: Usually means Redis or PostgreSQL is not running.
  • NUQ_DATABASE_URL Error: Ensure the correct schema is initialized in the database.
  • Scraping Failure: Local mode lacks a global proxy pool by default and is limited by your current local network environment.