Papermake, Typst 템플릿을 사내 PDF API로 바꿔줘요

Papermake, Typst 템플릿을 사내 PDF API로 바꿔줘요

AI 뉴스 썸네일

청구서나 증명서 PDF를 여러 서비스에서 만들면 템플릿 배포와 결과 추적이 금세 복잡해져요. Papermake는 Typst 템플릿을 서버에 한 번 올린 뒤 REST API로 렌더링하는 오픈소스 서버예요. 템플릿 버전, 입력 데이터, 출력 PDF의 해시를 함께 기록해 어떤 문서가 어떻게 만들어졌는지 다시 확인할 수 있어요. 1

핵심 요약

구분	핵심	왜 볼 만한가요
템플릿 운영	변경할 수 없는 버전과 최신 버전을 가리키는 태그를 함께 지원해요	배포된 문서 양식과 개발 중인 양식을 분리하기 쉬워요
PDF 생성	클라이언트는 Typst를 설치하지 않고 HTTP 요청으로 PDF를 만들어요	여러 서비스가 같은 문서 생성 방식을 공유할 수 있어요
재현성	템플릿과 파일을 SHA-256 해시로 저장하고 렌더링 이력을 남겨요	과거 PDF가 어느 템플릿과 데이터에서 나왔는지 추적할 수 있어요
운영 조건	Rust 실행 파일 외에 S3 호환 저장소와 ClickHouse가 필요해요	단순 라이브러리보다 무겁지만 사내 문서 플랫폼으로 운영하기 좋아요

1. Typst 템플릿을 배포 가능한 PDF 서비스로 묶었어요

Papermake는 Typst 렌더러를 HTTP 서버와 템플릿 저장소로 감싼 프로젝트예요. 개발자는 `invoice:v1.0.0`처럼 고정된 버전을 발행하거나 `invoice:latest`처럼 이동하는 태그를 만들 수 있어요. 고정 버전은 한 번 발행하면 바뀌지 않고, 태그는 새 버전의 위치를 가리키도록 갱신할 수 있어요. 컨테이너 이미지의 버전과 태그를 다루는 방식과 닮았어요. 2

PDF를 만들 때는 템플릿 참조와 JSON 데이터를 렌더링 API에 보내요. 서버는 작업을 마친 뒤 `render_id`, PDF 해시, 처리 시간을 돌려줘요. 클라이언트는 이 ID로 완성된 PDF를 내려받을 수 있어요. 템플릿에 로고, 글꼴, 다른 Typst 파일이 필요하면 함께 업로드할 수 있고, 입력값을 검사할 JSON Schema도 붙일 수 있어요.

728x90

저장 방식도 문서 재현성에 초점을 맞췄어요. 템플릿과 첨부 파일은 SHA-256 해시를 기준으로 저장돼 같은 파일을 여러 번 보관하지 않아요. 각 템플릿 버전은 파일 이름과 해시의 관계를 매니페스트로 남겨요. 렌더링 기록에는 입력 데이터와 출력물의 해시가 들어가므로, 나중에 특정 PDF가 어떤 양식과 데이터로 생성됐는지 확인할 수 있어요.

문서가 바뀌어도 과거 결과를 다시 확인할 수 있어요

청구서, 계약 부속 문서, 증명서처럼 발행 당시 양식을 보존해야 하는 문서에서는 `latest`만 사용하면 곤란해요. 새 디자인을 배포한 뒤 과거 문서를 다시 만들 때 결과가 달라질 수 있기 때문이에요. Papermake의 고정 버전을 문서 레코드와 함께 저장하면 당시 템플릿을 지정해 다시 렌더링할 수 있어요. 입력과 출력 해시도 남아 변경 여부를 대조하기 쉬워요.

PDF/A-2b와 PDF/A-3b 출력도 지원해요. PDF/A-3b는 파일 첨부를 허용해 ZUGFeRD나 Factur-X 같은 전자 청구서 형식의 기반으로 쓰여요. 다만 특정 전자문서 규격을 완성하려면 필요한 XML 구조와 업무 규칙을 애플리케이션에서 별도로 맞춰야 해요. PDF/A 옵션 하나만 켠다고 규격 준수가 끝나는 것은 아니에요.

빠른 실험과 운영 배포의 구성을 나눠 봐야 해요

Docker Compose를 실행하면 Papermake 서버, MinIO, ClickHouse가 함께 올라와요. 서버는 기본적으로 3000번 포트에서 요청을 받고, MinIO는 템플릿과 결과 파일을 저장하며, ClickHouse는 렌더링 이력을 맡아요. 로컬 실험은 간단하지만 운영 환경에서는 세 구성 요소의 백업과 접근 제어를 함께 설계해야 해요.

핵심 렌더러만 필요한 팀은 Rust 라이브러리로 사용할 수도 있어요. 이 방식은 서버와 저장소를 운영하지 않아도 되지만, 템플릿 레지스트리와 감사 이력은 애플리케이션에서 직접 만들어야 해요. 반대로 여러 서비스가 같은 양식을 공유하거나 발행 이력을 중앙에서 관리해야 한다면 HTTP 서버 구성이 더 잘 맞아요.

공개 저장소의 작업 큐 기반 렌더 워커는 아직 초기 뼈대 단계로 표시돼 있어요. 대량 생성 작업을 바로 맡기기 전에는 동시 요청 제한, 실패 재시도, 작업 격리, 처리량을 직접 시험해야 해요. 인증과 외부 노출 정책도 배포 환경에서 별도로 확인하는 편이 안전해요.

왜 중요한가요

PDF 생성 코드를 서비스마다 넣으면 같은 청구서 양식도 여러 곳에 복제돼요. 글꼴이나 로고를 바꿀 때 배포 대상이 늘고, 어느 버전으로 문서를 만들었는지 찾기도 어려워져요. Papermake는 템플릿 발행과 렌더링을 하나의 API로 모아 이런 운영 비용을 줄이는 방향을 택했어요. 2

도입 여부는 PDF 생성 횟수보다 문서의 수명과 책임 범위를 먼저 보고 정하는 게 좋아요. 한 서비스에서 간단한 영수증 몇 장을 만드는 정도라면 Typst 라이브러리를 직접 호출하는 편이 가벼워요. 여러 팀이 같은 양식을 쓰고, 과거 결과 재현이나 변경 이력이 필요하다면 중앙 레지스트리의 가치가 커져요.

시험할 때는 실제 템플릿으로 세 가지를 확인해 보세요. 같은 버전과 데이터가 같은 결과를 내는지, 글꼴과 이미지가 포함된 문서에서도 렌더링이 안정적인지, S3나 ClickHouse 장애 뒤 작업 이력을 복구할 수 있는지 확인하면 돼요. 개인정보가 입력 데이터에 들어간다면 보관 기간, 암호화, 삭제 절차도 운영 전에 정해야 해요.

참고 자료

1. Papermake - Typst 기반의 셀프 호스팅 가능한 PDF 문서 생성 서버 — GeekNews
2. Papermake: Turn Typst templates into PDF APIs — GitHub