instagram-card-news 엔진이란?
instagram-card-news는 오픈소스 카드뉴스 생성 엔진입니다. Node.js와 Puppeteer 기반으로 동작하며, HTML 템플릿을 입력으로 받아 PNG 이미지를 출력합니다. 별도의 이미지 생성 AI 없이도 서버 안에서 완성된 카드뉴스 이미지를 만들 수 있습니다.
차은별 에이전트가 주제를 받아 카피를 작성하면, 이 엔진이 그 텍스트를 받아 실제 이미지 파일로 변환합니다. 에이전트 → 슬라이드 데이터 생성 → 엔진 실행 → PNG 출력의 흐름이 서버 안에서 완결됩니다. Midjourney나 DALL-E 같은 외부 이미지 AI를 매번 호출할 필요가 없습니다.
설치 전 확인 사항
설치를 시작하기 전에 두 가지를 먼저 확인합니다.
Node.js 버전을 확인합니다. node --version 명령으로 18 이상인지 봅니다. Puppeteer가 Node.js 18 이상을 권장합니다. 낮은 버전이면 일부 기능이 동작하지 않을 수 있습니다.
서버 운영체제를 확인합니다. Chromium과 관련 의존성 패키지명이 Ubuntu와 Debian에서 다를 수 있습니다. lsb_release -a 명령으로 배포판을 확인해둡니다.
1단계: 엔진 클론과 npm 설치
워크스페이스 경로로 이동합니다. cd ~/.openclaw/workspace-chaeunbyul 을 실행합니다.
instragram-card-news 리포지토리를 클론합니다. 폴더명을 chaeunbyul-engine으로 지정합니다. 기본 이름인 instagram-card-news보다 에이전트 이름 기반으로 관리하는 것이 나중에 에이전트가 늘었을 때 혼선이 없습니다.
git clone https://github.com/junghwaYang/instagram-card-news.git chaeunbyul-engine cd chaeunbyul-engine npm install
npm install 중에 Puppeteer가 Chromium 바이너리를 자동으로 다운로드합니다. 서버 속도에 따라 3~10분 정도 걸릴 수 있습니다. 완료 메시지가 나올 때까지 기다립니다.
2단계: 한글 폰트 설치
이 단계를 빠뜨리면 생성된 이미지에서 한국어 텍스트가 모두 □□□으로 깨져 보입니다. 서버에 한글 폰트가 없으면 Puppeteer가 렌더링할 때 폰트를 찾지 못하기 때문입니다.
sudo apt-get install -y fonts-noto-cjk
Noto CJK는 한국어, 중국어, 일본어를 모두 지원하는 구글 폰트 패키지입니다. 인스타그램 카드뉴스에 쓰이는 대부분의 한국어 텍스트를 깔끔하게 렌더링합니다.
설치 후 fc-cache -fv를 실행해서 폰트 캐시를 갱신합니다. 일부 환경에서는 이 단계를 건너뛰면 폰트가 즉시 반영되지 않을 수 있습니다.
3단계: Puppeteer 의존성 설치
Puppeteer는 헤드리스 Chromium을 사용합니다. 서버 환경에는 브라우저 실행에 필요한 그래픽·오디오 관련 라이브러리가 기본적으로 설치되어 있지 않은 경우가 많습니다.
sudo apt-get install -y chromium libatk1.0-0 libatk-bridge2.0-0 libcups2 libxdamage1 libxrandr2 libgbm1 libpango-1.0-0 libcairo2 libnss3 libxss1 libasound2t64
Ubuntu 22.04 이상에서는 chromium 패키지를 사용합니다. chromium을 찾을 수 없는 경우, Ubuntu 22.04 미만이라면 chromium-browser로 패키지명을 바꿔서 시도합니다.
4단계: 샘플 렌더 테스트
모든 설치가 끝나면 샘플 이미지를 생성해서 정상 동작하는지 확인합니다.
node scripts/generate-samples.js
이 스크립트가 완료되면 sample-output/ 폴더에 PNG 파일들이 생겨납니다. 파일이 생겼고 한글이 깨지지 않았으면 설치 성공입니다.
자주 발생하는 오류
error while loading shared libraries: 3단계 의존성 라이브러리 중 일부가 빠진 것입니다. 오류 메시지에서 어떤 라이브러리가 없는지 확인하고 해당 패키지를 추가로 설치합니다.
폰트는 설치했는데 여전히 깨짐: Puppeteer에 별도로 폰트 경로를 지정해야 하는 환경이 있습니다. generate 스크립트 상단에 FONTCONFIG_PATH 환경 변수를 지정하는 방식으로 해결합니다.
SIGKILL 또는 메모리 오류: 서버 메모리가 부족할 때 Puppeteer가 강제 종료됩니다. 최소 1GB RAM이 있어야 Chromium이 안정적으로 동작합니다. 작은 VPS 서버에서는 swap을 추가로 설정하는 것도 방법입니다.
systemd --user 관련 오류: openclaw gateway start 명령이 systemd user service를 사용하는데, 컨테이너 환경에서는 이 방식이 동작하지 않습니다. 이 경우 openclaw gateway 를 직접 실행하고 nohup으로 백그라운드 처리합니다.
