TL;DR

ComPDF Self-Hosted는 Docker Compose로 즉시 배포 가능한 오픈소스 PDF 편집·변환 스택으로서 브라우저 기반 Web UI와 미들웨어 API 프록시를 함께 제공해 클론-환경설정-기동의 단순한 절차로 온프레미스 문서 센터를 구축할 수 있다. 내부적으로 compdf-server가 UI와 API 프록시 역할을 수행하고 compdf-app이 변환 작업을 처리하며 compdf-infra의 MySQL·Redis·RustFS가 상태와 파일 스토리지를 관리하는 구조이다. 기본 무료 에디션은 워터마크 및 페이지 제한이 존재하며 엔터프라이즈 라이선스는 워터마크 제거와 무제한 페이지 처리, 상업용 라이선스 및 기술 지원을 제공해 그 제약을 해소한다. 로컬 개발용으로는 docker-compose.dev.yml과 Vite 기반 프론트엔드 핫리로드가 지원되어 기능 개발과 디버깅이 용이하다.

주요 기능

• PDF 병합·분할·회전·페이지 삽입·삭제 같은 편집 작업을 브라우저에서 수행한다.
• PDF와 Word/Excel/Slide/HTML/TXT/CSV/RTF/JSON 등 다수 형식 간의 일괄 변환을 제공한다.
• 이미지 파일을 Word/Excel/Slide/HTML/CSV/TXT/RTF/PDF 등으로 변환하는 이미지 변환 파이프라인을 제공한다.
• API 키와 라이선스 토큰 기반의 접근 제어 및 엔터프라이즈용 라이선스 관리를 지원한다.
• Docker Compose 기반의 단일 명령 기동으로 전체 스택을 로컬 또는 온프레미스 환경에 배포한다.

어떻게 동작하는가

브라우저 요청은 compdf-server 컨테이너의 Web UI로 들어오고 미들웨어는 /api/v1/* 경로를 통해 변환·편집 API를 프록시한다. 실제 변환 작업은 compdf-app 컨테이너가 처리하며 compdf-infra 컨테이너의 MySQL, Redis, RustFS를 통해 상태·세션·파일 스토리지를 관리한다. 전체 구성은 Docker Compose로 묶여 있고 프로젝트 루트의 configs와 storage 디렉터리를 컨테이너에 마운트해 영구 저장과 설정 주입을 수행한다.

해결 문제

사내 온프레미스 환경에서 PDF 편집과 다양한 포맷 간 변환을 신속히 구축해야 하는 문제를 해결한다. 타 SDK처럼 심층 통합을 요구하지 않고 Docker Compose로 전체 스택을 즉시 배포할 수 있어 통합 개발 비용과 초기 설정 시간을 줄인다. 또한 API 기반 접근과 브라우저 UI를 함께 제공해 자동화 파이프라인과 사람이 직접 쓰는 운영 인터페이스를 동시에 만족시킨다.

지금 주목받는 이유

프라이빗 배포와 Docker 기반의 즉시 배포성을 결합해 내부 문서센터와 자동화 파이프라인 요구를 동시에 충족하므로 주목받고 있다.

차별점

• 전체 편집·변환 파이프라인을 단일 Docker Compose 구성으로 제공해 배포·재현성을 단순화한다.
• 브라우저 기반의 완전한 Web UI와 미들웨어 API 프록시를 모두 포함해 별도 통합 개발 없이 즉시 사용 가능하다.
• 엔터프라이즈 라이선스 옵션으로 워터마크 제거·무제한 페이지 처리·상업용 라이선스를 제공해 무료 에디션의 제약을 해소한다.

사용 사례

• 사내 문서 플랫폼을 구축해 중앙에서 PDF 편집과 포맷 변환을 자동화하는 워크플로에 통합한다.
• 문서 처리 파이프라인에서 대량 문서의 포맷 변환과 OCR 기반 검색 가능 PDF 생성을 배치 작업으로 처리한다.
• 온프레미스 환경에서 고객 데이터가 포함된 PDF 변환 서비스를 제공하면서 라이선스 및 데이터 주권을 유지한다.

시작하기

프로덕션 구성은 레포지토리를 클론한 뒤 .env를 복사해 환경을 준비하고 docker compose up -d로 전체 스택을 기동하면 http://localhost:8080/에서 Web UI에 접속할 수 있다. 개발 환경은 docker-compose.dev.yml로 compdf-infra와 compdf-app을 먼저 기동한 뒤 서버 디렉터리의 환경 변수를 설정하고 npm run start:dev로 미들웨어를 로컬에서 실행하고 frontend/compdf-web에서 npm run dev로 Vite 개발 서버를 기동하면 핫 리로드 환경이 구성된다. 엔터프라이즈 라이선스를 적용하려면 COMPDF_LICENSE_KEY를 .env에 설정하고 서비스를 재시작하면 라이선스가 반영된다.

요구사항

• Docker 및 Docker Compose가 설치되어 있어야 하며 컨테이너 기동을 위한 충분한 디스크 공간과 포트(기본 8080 등) 접근이 가능해야 한다.
• 개발 시 Node.js와 npm이 필요하며 서버 및 프론트엔드 의존성 설치를 위해 네트워크 접근이 필요하다.
• 영구 저장을 위해 프로젝트 루트의 configs와 storage 디렉터리를 호스트에 마운트할 권한이 필요하다.

이미지 분석