Ubuntu 26.04.1 LTS - wkhtmltopdf 설치 및 한글 폰트 설정 가이드

# Ubuntu 26.04.1 LTS - wkhtmltopdf 설치 및 한글 폰트 설정 가이드

## 1. 개요

Ubuntu 26.04(Resolute) 저장소에서는 `wkhtmltopdf` 개발 프로젝트 중단(Deprecated)으로 인해 공식 APT 기본 패키지 목록에서 제외되었습니다.

따라서 의존성 패키지와 한글 폰트(`fonts-nanum`)를 우선 설치한 뒤, 호환 패키지(`.deb`)를 다운로드하여 직접 설치해야 합니다.

## 2. 사전 준비 및 의존성 설치

`wkhtmltopdf` 실행에 필요한 그래픽 및 렌더링 라이브러리와 한글 폰트 패키지를 설치합니다.

```bash
# 패키지 목록 업데이트 및 의존성 라이브러리/한글 폰트 설치
apt update
apt install -y fonts-nanum xfonts-75dpi xfonts-base libjpeg-turbo8 libx11-6 libxcb1 libxext6 libxrender1
```

## 3. wkhtmltopdf 패키지 다운로드 및 설치

공식 릴리즈의 바이너리 패키지를 다운로드하여 설치합니다.

```bash
# 1. 패키지 다운로드(Jammy 호환 패키지)
wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-2/wkhtmltox_0.12.6.1-2.jammy_amd64.deb

# 2. 패키지 설치
dpkg -i wkhtmltox_0.12.6.1-2.jammy_amd64.deb

# 3. 누락된 의존성(fontconfig 등) 자동 교정 및 설치 완료
apt install -f -y

# 4. 임시 설치 파일 삭제
rm -f wkhtmltox_0.12.6.1-2.jammy_amd64.deb
```

## 4. 설치 확인 및 검증 테스트

### 4.1 버전 확인

실행 파일의 버전을 확인합니다.

```bash
wkhtmltopdf --version
```

정상 출력 예시:

```text
wkhtmltopdf 0.12.6.1 (with patched qt)
```

### 4.2 한글 렌더링 및 PDF 변환 테스트

한글 웹사이트 접속 및 PDF 생성이 정상적으로 수행되는지 검증합니다.

```bash
# 네이버 메인 페이지 PDF 생성 테스트
wkhtmltopdf --page-size A4 https://www.naver.com /tmp/naver_test.pdf
```

### 4.3 생성 결과물 확인

`/tmp/naver_test.pdf` 파일이 생성되었는지 확인하고 한글 깨짐(네모 `□□□` 현상)이 없는지 검수합니다.

## 5. 트러블슈팅 및 참고 사항

### 5.1 한글 폰트 수동 설치 불필요

과거 리눅스 환경처럼 `NanumFont_TTF.zip`을 내려받아 `/usr/share/fonts/`에 수동으로 압축 해제할 필요가 없습니다.

`apt install fonts-nanum` 명령으로 시스템 공식 경로(`/usr/share/fonts/truetype/nanum`)에 정식 등록되며, 폰트 캐시도 자동으로 갱신됩니다.

### 5.2 X Server 연결 오류 발생 시(headless 지원)

디스플레이 설정 관련 오류(`cannot connect to X server`)가 발생할 경우 가상 디스플레이 버퍼 패키지를 추가로 설치하여 실행할 수 있습니다.

```bash
# Xvfb 설치(필요한 경우)
apt install -y xvfb

# CLI/PHP에서 실행할 경우
xvfb-run wkhtmltopdf [URL/HTML파일] [출력파일.pdf]
```