• "We Worship One Thing: Technology"

Ubuntu 24에 FireCrawl 설치

Ubuntu 24에 FireCrawl 설치

6 min read

본 절차에서는 다음 구성을 최종 목표로 합니다.

  1. FireCrowl (API서버 & 워커)을 Ubuntu 24에 설치
  2. Node.js는 시스템 전체에 설치하고, 전역으로 pnpm을 사용
  3. Rust 툴체인(rustup 등)을 도입하여 FireCrawl의 Rust 기반 HTML 변환 라이브러리(html-transformer)를 빌드
  4. Playwright 의존 패키지 설치 및 독자적인 Playwright 마이크로서비스 스크립트 작성
  5. FireCrowl 시작용 systemd 서비스 2개(서버용 & 워커용)를 생성하여,
    • OS 부팅 시 자동으로 시작
    • 수동으로 sudo systemctl restart firecrowl-server / sudo systemctl restart firecrowl-workers 등을 실행 가능
                                      (선택 사항)
                                 +-----------------+
                                 |      Dify       |
                                 +-----------------+
                                          |
                                          | HTTP / REST API
                                          v
+------------------------------------------------------------------+
| FireCrawl (Node.js, TypeScript, pnpm)                            |
|  디렉토리: /home/firecrawl/apps/api                              |
|                                                                  |
|  +----------------------+      (pnpm run start)                 |
|  |   API 서버           |-----------------------------------------+
|  | - Express            |                                         |
|  | - BullMQ Dashboard   |                                         |
|  +----------------------+                                         |
|             ^                                                    |
|             | (큐 작업)                                          |
|  +----------------------+      (pnpm run workers)                |
|  |   워커               |-----------------------------------------+
|  | - 스크래핑, 파싱,    |                                         |
|  |   인덱싱             |                                         |
|  +----------------------+                                         |
|                                                                  |
|  - .env로 설정된 각종 옵션(API 키, PORT, HOST,                  |
|    PLAYWRIGHT_MICROSERVICE_URL 등)                                 |
|                                                                  |
|  - Rust HTML Transformer:                                        |
|      -> Cargo를 통해 빌드:                                        |
|         /home/firecrawl/apps/api/sharedLibs/html-transformer       |
|      -> 생성: libhtml_transformer.so                              |
|      -> FireCrawl에서 빠른 HTML 파싱에 사용 (또는 Cheerio로 폴백)   |
+------------------------------------------------------------------+
                                          |
                                          | 작업 큐 / 속도 제한
                                          v
+----------------------------------+
|        Redis (localhost)         |
|  - BullMQ 작업 큐에 사용         |
+----------------------------------+


+---------------------------------------------+
| systemd (Ubuntu 24)                        |
|                                             |
|  +--------------------------+               |
|  | firecrowl-server         |               |
|  | - ExecStart=pnpm run start|               |
|  +--------------------------+               |
|  +--------------------------+               |
|  | firecrowl-workers        |               |
|  | - ExecStart=pnpm run     |               |
|  |   workers                |               |
|  +--------------------------+               |
|  +--------------------------+               |
|  | firecrowl-playwright     |               |
|  | - ExecStart=pnpm run     |               |
|  |   playwright-service     |               |
|  +--------------------------+               |
|  (부팅 시 자동 시작, 프로세스 모니터링,      |
|   systemd를 통한 로그 관리)                  |
+---------------------------------------------+

전제 조건:

  • Ubuntu 24 (코드명 “noble”)에서 Docker 없이 실행
  • OS 사용자는 관리자 권한으로 작업 가능
  • FireCrowl 리포지토리를 /home/firecrawl에 클론하는 것을 가정
  • Redis가 설치 완료 (sudo apt install -y redis-server)되어 실행 중

STEP1. 시스템 준비 및 Node.js / pnpm 설치 #

STEP1.1 시스템 업데이트 및 개발 도구 설치 #

sudo apt update
sudo apt install -y build-essential pkg-config curl git libssl-dev

STEP1.2 NodeSource에서 Node.js 설치 #

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

STEP1.3 pnpm 전역 설치 #

sudo npm install -g pnpm

※which pnpm으로 실행 경로(예: /usr/local/bin/pnpm)를 확인하세요.

STEP2. FireCrawl 리포지토리 클론 및 의존 패키지 설치 #

STEP2.1 FireCrawl 클론 #

cd /home/firecrawl
git clone https://github.com/mendableai/firecrawl.git

STEP2.2 의존 패키지 설치 #

cd /home/firecrawl/apps/api
pnpm install

STEP2.3 .env 파일 설정 #

/home/firecrawl/apps/api/.env를 생성 또는 편집하여 필요한 환경 변수를 설정합니다. 예:

# ===== Required ENVS ======
NUM_WORKERS_PER_QUEUE=8
PORT=3002
HOST=0.0.0.0
REDIS_URL=redis://localhost:6379
REDIS_RATE_LIMIT_URL=redis://localhost:6379
PLAYWRIGHT_MICROSERVICE_URL=http://localhost:3000/html
USE_DB_AUTHENTICATION=false

# ===== Optional ENVS ======
TEST_API_KEY=fc-bestnet
BULL_AUTH_KEY=fc-bestnet
...(기타 옵션은 필요에 따라)

STEP3. Rust 툴체인 도입 및 HTML Transformer 빌드 #

STEP3.1 Rust 툴체인 설치 #

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
rustc --version
cargo --version

STEP3.2 FireCrawl 내 Rust 라이브러리 디렉토리 확인 #

리포지토리 루트에서 다음 명령을 실행하여 Cargo.toml이 있는 디렉토리를 찾습니다.

cd /home/firecrawl
find . -type f -name Cargo.toml | grep -i html-transformer

예: ./sharedLibs/html-transformer/Cargo.toml이 발견되면 해당 디렉토리로 이동합니다.

STEP3.3 Rust 라이브러리 빌드 #

cd /home/firecrawl/sharedLibs/html-transformer
cargo build --release

빌드 성공 시 target/release/libhtml_transformer.so가 생성됩니다. 확인:

ls target/release/libhtml_transformer.so

STEP3.4 라이브러리 배치 또는 환경 변수 설정 #

  • 방법 A: FireCrawl의 Node.js 코드가 상대 경로로 읽어들이면 특별한 작업 불필요
  • 방법 B: 필요에 따라 LD_LIBRARY_PATH에 추가
export LD_LIBRARY_PATH=/home/firecrawl/sharedLibs/html-transformer/target/release:$LD_LIBRARY_PATH

systemd로 자동 설정하려면 서비스 파일에
Environment=LD_LIBRARY_PATH=...를 추가하세요.

STEP4. Playwright 설정 및 마이크로서비스 스크립트 생성 #

STEP4.1 Playwright 의존 패키지 설치 #

Ubuntu 24.04용 의존 라이브러리 예시:

sudo apt-get install -y libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 libcups2 
    libdrm2 libxkbcommon0 libgtk-3-0 libpango-1.0-0 libcairo2 libgdk-pixbuf2.0-0 
    libgbm1 libatspi2.0-0 libx11-xcb1 libxcomposite1 libxdamage1 libxfixes3 
    libxrandr2 libxrender1 libxtst6 libxcb1 libxi6 libxcursor1 ca-certificates 
    fonts-liberation xdg-utils

STEP4.2 Playwright 브라우저 설치 #

pnpm exec playwright install

STEP4.3 Playwright 마이크로서비스용 스크립트 생성 #

/home/firecrawl/apps/api에 playwright-service.js를 생성하고, 다음 코드 예제를 붙여넣습니다.

// playwright-service.js
const http = require('http');
const { chromium } = require('playwright');

const PORT = 3000;

const server = http.createServer(async (req, res) => {
  if (req.method === 'GET' && req.url.startsWith('/html')) {
    try {
      const urlParam = new URL(req.url, `http://localhost:${PORT}`).searchParams.get('url');
      if (!urlParam) {
        res.writeHead(400, { 'Content-Type': 'text/plain' });
        return res.end('Missing ?url parameter');
      }
      const browser = await chromium.launch({ headless: true });
      const page = await browser.newPage();
      await page.goto(urlParam, { waitUntil: 'networkidle' });
      const content = await page.content();
      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
      res.end(content);
      await browser.close();
    } catch (err) {
      console.error('Playwright microservice error:', err);
      res.writeHead(500, { 'Content-Type': 'text/plain' });
      res.end('Playwright error occurred');
    }
  } else {
    res.writeHead(404, { 'Content-Type': 'text/plain' });
    res.end('Not found');
  }
});

server.listen(PORT, '0.0.0.0', () => {
  console.log(`Playwright microservice listening on http://0.0.0.0:${PORT}/html`);
});

STEP4.4 package.json에 스크립트 추가 #

/home/firecrawl/apps/api/package.json의 "scripts"에 아래 내용을 추가하세요(기존 항목과 병합).

"playwright-service": "node playwright-service.js"

STEP5. Systemd 서비스 설정 #

FireCrawl 서버, 워커, Playwright 마이크로서비스를 자동 시작하도록 systemd 유닛 파일을 생성합니다.

STEP5.1 FireCrawl 서버 서비스 (/etc/systemd/system/firecrowl-server.service) #

[Unit]
Description=FireCrowl Server
After=network.target

[Service]
User=firecrawl
Group=firecrawl
WorkingDirectory=/home/firecrawl/apps/api
Environment=PATH=/usr/local/bin:/usr/bin:/bin
ExecStart=/bin/bash -c 'pnpm run start'
Restart=always
RestartSec=5
Type=simple

[Install]
WantedBy=multi-user.target

STEP5.2 FireCrawl 워커 서비스 (/etc/systemd/system/firecrowl-workers.service) #

[Unit]
Description=FireCrowl Workers
After=network.target

[Service]
User=firecrawl
Group=firecrawl
WorkingDirectory=/home/firecrawl/apps/api
Environment=PATH=/usr/local/bin:/usr/bin:/bin
ExecStart=/bin/bash -c 'pnpm run workers'
Restart=always
RestartSec=5
Type=simple

[Install]
WantedBy=multi-user.target

STEP5.3 Playwright 마이크로서비스 서비스 (/etc/systemd/system/firecrowl-playwright.service) #

[Unit]
Description=FireCrowl Playwright Microservice
After=network.target

[Service]
User=firecrawl
Group=firecrawl
WorkingDirectory=/home/firecrawl/apps/api
Environment=PATH=/home/firecrawl/.nvm/versions/node/v20.18.3/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=/bin/bash -c 'pnpm run playwright-service'
Restart=always
RestartSec=5
Type=simple

[Install]
WantedBy=multi-user.target

주의:

  • User=firecrawl을 사용하는 경우, 미리 firecrawl 사용자를 생성하고 sudo chown -R firecrawl:firecrawl /home/firecrawl 등으로 소유권을 설정해 둡니다.
  • Environment=PATH=...에서는 nvm 경유 설치의 Node.js 경로를 지정하고 있습니다. 환경에 맞게 수정하세요.
  • Rust 라이브러리를 상대 경로로 읽어들이지 않는 경우, LD_LIBRARY_PATH 설정도 필요합니다.

STEP5.4 Systemd 서비스 활성화 및 시작 #

sudo systemctl daemon-reload
sudo systemctl enable firecrowl-server
sudo systemctl enable firecrowl-workers
sudo systemctl enable firecrowl-playwright
sudo systemctl start firecrowl-server
sudo systemctl start firecrowl-workers
sudo systemctl start firecrowl-playwright

sudo systemctl status <service> 로 각 서비스가 active (running) 상태인지 확인하세요.

STEP6. FireCrawl 재시작 및 검증 #

  1. .env 설정 확인:
    특히 PLAYWRIGHT_MICROSERVICE_URL이 http://localhost:3000/html로 되어 있는지 확인 필요
  2. FireCrawl 서버 및 워커 기동:
    로그에 “Scrape via fetch…”등이 표시되면 HTTP 요청이 정상적으로 작동하고 있습니다
  3. Playwright 서비스 동작 확인:
    브라우저에서 http://<서버IP>:3000/html?url=https://example.com에 접속하여 HTML이 반환되면 정상

STEP7. 최종 확인 #

  • Rust 라이브러리:
    target/release/libhtml_transformer.so가 존재하고 로그에 오류가 표시되지 않는지 확인
  • Playwright 마이크로서비스:
    정상적으로 기동되어 JavaScript 렌더링이 수행되는지 테스트
  • 전체 연계:
    FireCrawl 서버·워커·Playwright가 연계되어 Dify 등으로부터의 요청에 정상 응답하는지 최종 확인
Updated on 2026년 6월 9일

What are your feelings

  • Happy
  • Normal
  • Sad
目次
서비스
AI 솔루션
리소스

©2020 BESTNET.LLC . All Rights Reserved.

Linkedin-in