Guide on Self Hosting Firecrawl on Ubuntu

Firecrawl is a powerful open-source tool for converting web pages and sites into clean, LLM-ready formats like Markdown, HTML, screenshots, structured data, and more. While Docker is commonly used to simplify deployment, you might prefer a native Ubuntu setup—for better control, transparency, or development convenience. Here’s how to do it. 

There is also a guide on how to set it up locally but some information in the guide is outdated and may not be working as expected if you just blindly follow it. However you can always use it as a reference.

Prerequisites

Before starting, ensure you have:

• Node.js (>=18 LTS) installed
• pnpm for package management
• Redis running locally (localhost:6379) for job queues

Installation Steps

1. Install Dependencies

# Install Node.js
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs build-essential

# Install pnpm globally
curl -fsSL https://get.pnpm.io/install.sh | sh -

# Install Redis
sudo apt-get install lsb-release curl gpg
curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg
sudo chmod 644 /usr/share/keyrings/redis-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/redis.list
sudo apt-get update
sudo apt-get install redis

2. Clone the Firecrawl Repository and Build

Go to GitHub and clone the repository to local directory

git clone https://github.com/mendableai/firecrawl.git
cd firecrawl/apps/api

3. Configure Environment Variables

Copy the example config and update it:

cp .env.example .env
# Edit .env to include:
NUM_WORKERS_PER_QUEUE=8
PORT=3002
HOST=0.0.0.0
REDIS_URL=redis://localhost:6379
REDIS_RATE_LIMIT_URL=redis://localhost:6379

# for local, we can bypass Auth first, otherwise may need Supabase setup
USE_DB_AUTHENTICATION=false

Other parameters in the file can lease them as is. Feel free to add any optional env vars as needed. If you need to scrape content and save as screenshot, you may need to set up Playwright and configure the service address in .env as well. If you are not planning to do that at the moment, can leave that as is.

4. Start the Services

Run these commands in separate terminals:

# Terminal A: Start Redis
sudo systemctl start redis-server

# Terminal B: Start the Worker
cd firecrawl/apps/api
PORT=3003 pnpm run workers

# Terminal C: Start the API Server
cd firecrawl/apps/api
pnpm run start

Note that when starting the workers, you need to explicitly set a port so that it will not listen at 3002 set in .env as it will be used when starting the api server. Otherwise you would see below error.

2025-09-04 15:23:23 info [:]: Worker 34522 started 
node:events:497
      throw er; // Unhandled 'error' event
      ^

Error: listen EADDRINUSE: address already in use 0.0.0.0:3002
    at Server.setupListenHandle [as _listen2] (node:net:1940:16)
    at listenInCluster (node:net:1997:12)
    at node:net:2206:7
    at process.processTicksAndRejections (node:internal/process/task_queues:90:21)
Emitted 'error' event on WebSocketServer instance at:
    at Server.emit (node:events:519:28)
    at emitErrorNT (node:net:1976:8)
    at process.processTicksAndRejections (node:internal/process/task_queues:90:21) {
  code: 'EADDRINUSE',
  errno: -98,
  syscall: 'listen',
  address: '0.0.0.0',
  port: 3002
}

Node.js v22.19.0

5. Test Your Setup

Use curl to validate that the API is responsive:

curl -X POST http://localhost:3002/v2/scrape \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://www.pixelstech.net/document/aboutus.php", "formats":["markdown","html"]}'

You should receive structured output including Markdown and HTML.

This indicates the setup works. You can explore more options provided by Firecrawl now.

This streamlined setup keeps everything transparent and customizable—perfect for development, contributions, or finely tuned self-hosting. In the next post we would provide the way to scrape as screenshot using Playwright.