(Ubuntu 24 ― 싱글 노드 / systemd / Playwright MS)

사전 조건 #

• 이미 /home/firecrawl에 구축 완료되어 systemd 서비스
  firecrowl-server·firecrowl-workers·firecrowl-playwright
  가 동작 중
• Node.js 20 & pnpm 10이 설치 완료
• Redis가 localhost:6379에서 실행 중

STEP 0 서비스 중지 & 백업 #

sudo systemctl stop firecrowl-server firecrowl-workers firecrowl-playwright
cd /home
sudo cp -r firecrawl firecrawl_backup_$(date +%Y%m%d)

STEP 1 리포지토리 최신화 #

1. 안전 디렉토리 등록(최초 1회만)

   git config --global --add safe.directory /home/firecrawl

2. shallow fetch로 최신 커밋으로 이동

   cd /home/firecrawl
   git fetch --depth 1 origin main
   git reset --hard origin/main

STEP 2 의존 패키지 클린 재설치 #

cd /home/firecrawl/apps/api
rm -rf node_modules pnpm-lock.yaml package-lock.json
pnpm install                                # 의존성을 최신으로 가져오기
pnpm approve-builds --all                   # postinstall 스크립트 허용

부족한 패키지 추가(이번에 필요했던 것) #

# Playwright 본체
pnpm add -D playwright
# domhandler 타입 누락 대응
pnpm add -D domhandler @types/domhandler

STEP 3 소스 수정(타입 오류 대응) #

다음 3개 파일에 패치를 적용합니다.

// 생략 … 
const meta = info.metadata as any;
return `${info.timestamp} ${info.level} [${meta.module ?? ""}:${meta.method ?? ""}]: ${info.message}`;
// 생략 …

documents: documents as unknown as string[],

import { Cheerio, load } from "cheerio";
import { AnyNode } from "domhandler";

STEP 4 프로덕션 빌드 방식으로 전환 (tsc→dist) #

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

"scripts": {
  "build": "tsc",
  "start:prod": "npm run build && node dist/src/index.js"
}

4-2 systemd 서비스 수정 #

/etc/systemd/system/firecrowl-server.service

[Service]
WorkingDirectory=/home/firecrawl/apps/api
EnvironmentFile=/home/firecrawl/apps/api/.env
ExecStart=/usr/bin/pnpm run start:prod
Restart=always
RestartSec=5

sudo systemctl daemon-reload

STEP 5 빌드 & 서비스 재시작 #

cd /home/firecrawl/apps/api
pnpm run build
sudo systemctl restart firecrowl-server firecrowl-workers firecrowl-playwright

STEP 6 동작 확인 #

• sudo systemctl status firecrowl-server가 active (running)
• curl http://localhost:3002/test → 200 OK
• 브라우저: http://<IP>:3002/admin/<TEST_API_KEY>/queues가 표시
• http://<IP>:3000/html?url=https://example.com → HTML이 반환됨

운영 중 업데이트(향후) #

1. git pull & pnpm install
2. pnpm run build
3. sudo systemctl restart firecrowl-server firecrowl-workers