본 절차에서는 다음 구성을 최종 목표로 합니다.
- FireCrowl (API 서버 & 워커) 을 Ubuntu 24 에 설치
- Node.js 는 시스템 전체에 설치하고, 전역으로
pnpm을 사용 - Rust 툴체인(rustup 등)을 도입하여 FireCrawl 의 Rust 제작 HTML 변환 라이브러리(html-transformer)를 빌드
- Playwright 의 의존 패키지 설치와 자체 Playwright 마이크로서비스 스크립트 작성
- FireCrowl 기동용 systemd 서비스 를 2개(서버용 & 워커용) 작성하여,
- OS 부팅 시 자동으로 기동
- 수동으로
sudo systemctl restart firecrowl-server/sudo systemctl restart firecrowl-workers등이 가능
(Optional) +-----------------+ | Dify | +-----------------+ | | HTTP / REST API v +------------------------------------------------------------------+ | FireCrawl (Node.js, TypeScript, pnpm) | | Directory: /home/firecrawl/apps/api | | | | +----------------------+ (pnpm run start) | | | API Server |-----------------------------------------+ | | - Express | | | | - BullMQ Dashboard | | | +----------------------+ | | ^ | | | (Queue tasks) | | +----------------------+ (pnpm run workers) | | | Workers |-----------------------------------------+ | | - Scraping, parsing, | | | | indexing | | | +----------------------+ | | | | - .env에 설정된 각종 옵션(API 키, PORT, HOST, | | PLAYWRIGHT_MICROSERVICE_URL 등) | | | | - Rust HTML Transformer: | | -> Built via Cargo in: | | /home/firecrawl/apps/api/sharedLibs/html-transformer | | -> Generates: libhtml_transformer.so | | -> Used by FireCrawl for fast HTML parsing (or falls back to | | Cheerio) | +------------------------------------------------------------------+ | | Task Queue / Rate Limit v +----------------------------------+ | Redis (localhost) | | - Used by BullMQ for job queuing| +----------------------------------+ +---------------------------------------------+ | systemd (Ubuntu 24) | | | | +--------------------------+ | | | firecrowl-server | | | | - ExecStart=pnpm run start| | | +--------------------------+ | | +--------------------------+ | | | firecrowl-workers | | | | - ExecStart=pnpm run | | | | workers | | | +--------------------------+ | | +--------------------------+ | | | firecrowl-playwright | | | | - ExecStart=pnpm run | | | | playwright-service | | | +--------------------------+ | | (Automatic start at boot, process monitoring,| | logs managed via 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-devSTEP1.2 NodeSource 에서 Node.js 설치 #
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejsSTEP1.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.gitSTEP2.2 의존 패키지 설치 #
cd /home/firecrawl/apps/api pnpm installSTEP2.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 --versionSTEP3.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.soSTEP3.4 라이브러리 배치 또는 환경 변수 설정 #
- 방법 A: FireCrawl 의 Node.js 코드가 상대 경로로 읽어들이는 경우 특별한 작업 불필요
- 방법 B: 필요에 따라
LD_LIBRARY_PATH에 추가
export LD_LIBRARY_PATH=/home/firecrawl/sharedLibs/html-transformer/target/release:$LD_LIBRARY_PATHsystemd 로 자동 설정하려면, 서비스 파일에
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-utilsSTEP4.2 Playwright 브라우저 설치 #
pnpm exec playwright installSTEP4.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.targetSTEP5.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.targetSTEP5.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-playwrightsudo systemctl status <service>로 각 서비스가active (running)상태인지 확인해 주세요.
STEP6. FireCrawl 재기동과 검증 #
- .env 설정 확인:
특히PLAYWRIGHT_MICROSERVICE_URL이http://localhost:3000/html로 되어 있는지 확인 필요 - FireCrawl 서버와 워커가 기동:
로그에 “Scrape via fetch…” 등이 나오면 HTTP 요청이 정상적으로 동작하고 있습니다 - Playwright 서비스 동작 확인:
브라우저에서http://<서버IP>:3000/html?url=https://example.com에 접속하여, HTML 이 반환되면 OK
STEP7. 최종 확인 #
- Rust 라이브러리:
target/release/libhtml_transformer.so가 존재하고, 로그에 오류가 발생하지 않는지 확인 - Playwright 마이크로서비스:
정상적으로 기동되어 JavaScript 렌더링이 이루어지는지 테스트 - 전체 연계:
FireCrawl 서버, 워커, Playwright 가 연계하여, Dify 등으로부터의 요청에 정상적으로 응답하는지 최종 점검
