PDF 변환을 위해 Docker에서 LibreOffice Headless를 실행하세요.

예. 일회성 문서 변환의 경우, LibreOffice가 설치된 소형 Docker 이미지를 빌드하고 soffice --headless다음 명령으로 실행하세요 --convert-to. 입력 디렉터리는 읽기 전용으로 마운트하고, 별도의 출력 디렉터리는 쓰기 권한으로 마운트하여 PDF 파일이 호스트에 표시되도록 합니다. 이 예제는 Debian 기반 이미지를 사용하고 DOCX 파일 하나를 PDF로 변환합니다. LibreOffice를 네트워크 서비스로 노출하지는 않습니다.

헤드리스 모드는 어떤 기능을 하며, Docker는 언제 유용할까요?

헤드리스 모드는 그래픽 인터페이스 없이 LibreOffice를 시작합니다. LibreOffice는 명령줄 및 API 제어 사용에 대한 이 모드를 문서화했으며, 명령줄 옵션은 출력 디렉터리를 지정하여 파일을 변환하는 기능을 지원합니다. Docker는 애플리케이션과 그 종속성을 패키징하므로 ​​스크립트나 워크스테이션에서 호스트에 데스크톱 제품군을 설치하지 않고도 동일한 컨테이너 이미지를 실행할 수 있습니다.

이 패턴은 로컬 배치 작업, CI 작업 또는 파일을 받아 변환 결과를 저장하는 백엔드 워커에 적합합니다. 일반 헤드리스 컨테이너는 그 자체로 HTTP 변환 API가 아닙니다. 포트를 사용하지 않고 웹 업로드도 허용하지 않습니다. 지속적인 서비스가 필요한 경우 변환 프로세스 주변에 API와 작업 큐를 배치하고 요청 유효성 검사, 시간 초과, 파일 크기 제한 및 격리 기능을 추가해야 합니다.

1. 입력 폴더와 출력 폴더를 생성합니다.

Linux 또는 macOS 호스트에서 Bash 또는 유사한 셸을 사용하여 프로젝트 폴더를 만들고 그 안에 별도의 디렉토리를 생성합니다. 소스 문서를 해당 디렉토리에 넣고 처음 실행할 때는 비워 input두십시오 .output

mkdir -p lo-work/input lo-work/output
cp report.docx lo-work/input/
cd lo-work

아래 Docker 명령어는 Unix 스타일의 경로와 셸 구문을 사용합니다. Windows에서는 PowerShell 또는 명령 프롬프트에 맞게 호스트 경로 구문을 조정하고 Docker Desktop이 해당 폴더가 포함된 드라이브를 공유할 수 있도록 허용해야 합니다.

2. LibreOffice를 사용하여 이미지 빌드

Dockerfile다음 내용을 포함 하는 파일을 생성하세요 lo-work:

FROM debian:bookworm-slim

RUN apt-get update && apt-get install -y --no-install-recommends \
    libreoffice-writer fonts-liberation \
    && rm -rf /var/lib/apt/lists/*

ENTRYPOINT ["soffice"]

libreoffice-writerWriter와 일반적인 워드 프로세싱 형식에 필요한 변환 필터를 제공합니다. 컨테이너가 스프레드시트나 프레젠테이션을 변환해야 하는 경우 libreoffice-calc해당 옵션을 추가하세요 libreoffice-impress. 글꼴 패키지는 기본 구성품일 뿐이므로 문서에 필요한 글꼴을 설치하고 사용 권한을 확보해야 합니다. 글꼴이 누락되면 줄 바꿈 및 페이지 나누기가 변경될 수 있습니다.

Dockerfile이 포함된 디렉토리에서 이미지를 빌드합니다.

docker build -t lo-headless .

이 예제에서는 Debian Bookworm 패키지 이름을 사용합니다. 기본 이미지 태그와 저장소 패키지는 시간이 지남에 따라 변경될 수 있습니다. 프로덕션 환경에서 빌드할 때는 유지 관리되는 기본 이미지를 선택하고, 보안 업데이트를 위해 정기적으로 다시 빌드하며, 재현 가능한 빌드가 필요한 경우 다이제스트를 사용하여 기본 이미지를 고정하십시오. 튜토리얼을 따라 하기 위해 관련 없는 저장소에서 패키지를 설치하는 것은 피하십시오.

3. LibreOffice를 개별 마운트로 실행

일회용 컨테이너를 시작하고 이미지 이름 뒤에 변환 옵션을 전달합니다. 입력 마운트는 읽기 전용이며 출력 디렉터리만 쓰기 가능합니다. `--` 옵션은 --userLinux에서 호스트 사용자 및 그룹 ID로 프로세스를 실행하고 HOME=/tmpLibreOffice에 쓰기 가능한 홈 디렉터리를 제공합니다. 호스트 사용자가 해당 디렉터리에 쓰기 권한이 없는 경우 폴더 권한을 조정하십시오 output.

docker run --rm \
  --user "$(id -u):$(id -g)" \
  --env HOME=/tmp \
  -v "$PWD/input:/input:ro" \
  -v "$PWD/output:/output" \
  lo-headless \
  --headless --nologo \
  -env:UserInstallation=file:///tmp/lo-profile \
  --convert-to pdf:writer_pdf_Export \
  --outdir /output \
  /input/report.docx

--headlessGUI를 숨기고 --convert-to pdf:writer_pdf_ExportPDF 내보내기 필터를 선택한 다음 --outdir마운트된 출력 폴더로 결과를 보냅니다. 고유한 사용자 프로필 경로를 통해 이 프로세스는 LibreOffice 구성 디렉터리에 쓰기 권한을 갖게 됩니다. 하나의 장기 실행 컨테이너에서 여러 변환 작업을 동시에 실행하는 경우 각 프로세스에 대해 서로 다른 프로필 경로를 사용하십시오.

--mountDocker의 보다 명확한 마운트 구문을 선호한다면 대신 를 사용하십시오 -v. 바인드 마운트는 Docker 데몬 호스트의 경로에 연결되고, 읽기/쓰기 마운트는 컨테이너 프로세스가 호스트 파일을 변경할 수 있도록 합니다. 마운트는 범위가 좁게 유지하고, 홈 디렉터리나 Docker 소켓을 마운트하지 마십시오. 또한 불필요한 권한으로 문서 변환 워커를 실행하지 마십시오.

4. PDF 파일이 생성되었는지 확인하십시오.

Docker가 종료된 후 호스트 출력 디렉토리를 확인하십시오.

ls -l output/
file output/report.pdf
test -s output/report.pdf

PDF 파일은 존재해야 하며 비어 있지 않아야 합니다. PDF 리더로 파일을 열어 페이지 수, 표, 이미지, 페이지 나누기 및 글꼴을 확인한 후 사용하십시오. 프로세스가 성공적으로 종료되었다고 해서 모든 요소가 의도대로 렌더링되었다는 것을 보장하는 것은 아닙니다. 특히 문서에서 컨테이너에 없는 글꼴이나 기능을 사용하는 경우에는 더욱 그렇습니다. 이전 PDF 파일이 최신 변환 파일로 오인되지 않도록 매번 실행할 때마다 깨끗한 출력 디렉터리를 사용하거나 새로운 출력 파일 이름을 사용하십시오.

변환이 실패하면 무엇을 확인해야 할까요?

• 출력 파일이 없습니다. 소스 파일 이름과 컨테이너 경로( input마운트 위치 포함 /input) 및 호스트 output디렉터리에 선택한 사용자가 쓰기 권한이 있는지 확인하십시오.
• 프로필 또는 잠금 오류: 경로에 쓰기 권한이 있는지 확인하십시오 -env:UserInstallation. 동시에 실행되는 각 LibreOffice 프로세스마다 별도의 프로필 디렉터리를 사용하십시오.
• 레이아웃이 변경되었습니다. 이미지에 필요한 글꼴을 설치하고 PDF를 검토하십시오. 글꼴 사용 가능 여부, 내보내기 필터 및 버전 차이로 인해 데스크톱 시스템과 렌더링 결과가 다를 수 있습니다.
• Docker 마운트 오류:-v 또는 를 사용하기 전에 두 호스트 디렉터리가 모두 존재하는지 확인 --mount하고 데몬이 해당 디렉터리에 접근할 수 있는지 확인하십시오.

옵션의 정확한 동작 방식은 LibreOffice의 명령줄 매개변수 참조를 확인하세요. 패키지 이름은 Debian Bookworm의 LibreOffice Writer 패키지 목록 에서 확인할 수 있습니다 . Docker 공식 문서에서는 바인드 마운트 및 Dockerfile 사용법을 설명합니다 .