Docker 컨테이너 내에서 LibreOffice를 헤드리스 모드로 실행하는 방법

흔히 발생하는 서버 측 문제는 처음에는 간단해 보입니다. 애플리케이션이 DOCX, XLSX, ODT 또는 PPTX 파일을 입력받아 PDF로 변환해야 하지만, 호스트 서버에서는 데스크톱 세션을 실행해서는 안 됩니다. 또한, 전체 오피스 제품군을 호스트 서버에 직접 설치하면 배포 재현이 더욱 어려워집니다. LibreOffice는 그래픽 인터페이스 없이도 실행할 수 있고, Docker를 사용하면 변환 런타임을 격리할 수 있지만, 안정적인 결과를 얻으려면 단순히 --headless명령어에 추가하는 것 이상의 조치가 필요합니다.

대부분의 오류는 실제적인 원인으로 예측 가능합니다. 이미지에 필요한 LibreOffice 구성 요소가 없거나, 컨테이너가 사용자 프로필을 저장할 수 없거나, 바인드 마운트된 파일의 권한이 잘못되었거나, 글꼴이 누락되었거나, 두 작업이 동일한 프로필을 공유하거나, 출력 디렉터리에 쓰기 권한이 없는 경우 등이 있습니다. 이 가이드는 가장 간단한 정상 작동 컨테이너부터 시작하여 반복 가능한 문서 변환을 위해 컨테이너를 강화하는 과정을 보여줍니다.

2026년 10월 현재, LibreOffice는 최신 기능 브랜치를 26.8로, 기업용으로 권장되는 안정적인 이전 브랜치를 26.2.6으로 명시하고 있습니다. Debian 13 안정 버전 패키지에는 배포판에서 관리하는 다른 버전의 LibreOffice가 포함될 수 있으므로, 기본 이미지를 고정하고 빌드된 컨테이너에서 실제 버전을 확인하는 것이 좋습니다. 업스트림 버전과 일치한다고 가정하지 마십시오. 자세한 내용은 LibreOffice 공식 릴리스 노트 와 Debian libreoffice-nogui 패키지 페이지를 참조하십시오 .

"Docker에서 헤드리스 LibreOffice"란 실제로 무엇을 의미하는가

LibreOffice는 --headless사용자 인터페이스 없이 실행되는 모드로 문서를 생성합니다. 파일 변환에 중요한 관련 옵션은 --convert-to및 입니다 --outdir. LibreOffice는 또한 사용자 프로필 디렉터리에 대한 쓰기 권한이 필요합니다. 이는 컨테이너를 루트가 아닌 사용자로 실행하거나 루트 파일 시스템을 읽기 전용으로 설정할 때 중요한 사항입니다. 공식적인 CLI 참조는 LibreOffice 도움말: 매개변수를 사용하여 LibreOffice 소프트웨어 시작하기를 참조 하십시오 .

따라서 좋은 컨테이너의 목표는 명확합니다. X11이나 데스크톱 없이 시작하여 입력 문서를 읽고 예상되는 출력 형식으로 작성하며, 깔끔하게 종료되고, 작업 부하에 적합한 레이아웃의 파일을 생성해야 합니다.

1단계: 작고 재현 가능한 Docker 이미지를 생성합니다.

Debian 13에서 다양한 형식을 지원하려면, libreoffice-noguiDebian에서 주로 스크립팅용으로 설계된 GUI가 없는 메타패키지라고 설명하는 이 패키지가 유용한 시작점이 될 수 있습니다. Writer 문서만 변환하는 경우에는 libreoffice-writer-nogui필요한 GUI가 없는 다른 구성 요소만 설치하여 종속성을 줄일 수 있습니다.

FROM debian:13-slim

ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update && apt-get install -y --no-install-recommends \
    libreoffice-nogui \
    fonts-dejavu-core \
    fonts-liberation2 \
    fonts-crosextra-carlito \
    fonts-crosextra-caladea \
    ca-certificates \
 && rm -rf /var/lib/apt/lists/*

RUN useradd --create-home --uid 10001 office

WORKDIR /work
USER office

ENTRYPOINT ["soffice","--headless","--nologo","--nodefault","--norestore"]

글꼴 패키지는 단순히 외관상의 문제가 아닙니다. 오피스 문서에서는 최소 Linux 이미지에 설치되지 않은 글꼴을 참조하는 경우가 많습니다. LibreOffice는 요청된 글꼴을 사용할 수 없는 경우 다른 글꼴로 대체하는데, 이로 인해 줄 바꿈, 페이지 수, 표 너비 및 슬라이드 레이아웃이 변경될 수 있습니다. Carlito와 Caladea는 Calibri 및 Cambria를 대체할 수 있는 유용한 미터법 호환 글꼴이며, Liberation과 DejaVu는 일반적인 경우에 적합합니다. 문서에 회사 또는 라이선스가 있는 글꼴을 사용하는 경우, 라이선스에서 허용하는 경우에만 해당 글꼴을 설치하거나 마운트하십시오.

2단계: 이미지를 빌드하고 LibreOffice 버전을 기록합니다.

docker build -t libreoffice-headless:debian13 .

그런 다음 이미지에 실제로 포함된 버전을 확인하십시오.

docker run --rm --entrypoint soffice   libreoffice-headless:debian13 --version

이 검사는 기본 이미지를 몇 주 후에 다시 빌드할 때 중요합니다. 정확한 렌더링이 중요한 경우, 프로덕션 환경에서는 변경 불가능한 이미지 다이제스트를 사용하고 보안 또는 LibreOffice 업데이트 후에 의도적으로 다시 빌드하십시오. "최신" 태그는 실험 중에 편리하지만 출력 차이를 조사하기 어렵게 만듭니다.

3단계: 입력 및 출력 디렉토리를 별도로 준비합니다.

호스트 디렉터리 두 개를 생성합니다. 입력 측은 읽기 전용으로 설정할 수 있으며, 출력 측은 컨테이너 사용자가 쓰기 권한을 가져야 합니다.

mkdir -p input output
cp sample.docx input/

Docker는 --mount바인드 마운트 구문을 권장합니다. 또한 Docker 문서에서는 바인드 마운트가 기본적으로 쓰기 가능하므로 소스 디렉터리를 명시적으로 읽기 전용으로 설정하는 것이 유용한 안전 장치라고 설명합니다. Docker 바인드 마운트 문서를 참조하세요 .

4단계: 문서 하나를 PDF로 변환합니다.

일회용 컨테이너를 실행하고 소스 디렉터리를 읽기 전용으로 마운트합니다.

docker run --rm   --mount type=bind,src="$(pwd)/input",dst=/input,readonly   --mount type=bind,src="$(pwd)/output",dst=/output   libreoffice-headless:debian13   --convert-to pdf   --outdir /output   /input/sample.docx

LibreOffice는 해당 --convert-to OutputFileExtension[:OutputFilterName[:OutputFilterParams]]형식을 공식적으로 지원합니다. 간단한 Writer-to-PDF 변환을 위해서는 --convert-to pdfLibreOffice가 적절한 PDF 내보내기 필터를 선택하도록 하십시오. 특정 PDF 동작이 필요한 경우 LibreOffice는 필터 매개변수에 대한 문서도 제공합니다. 공식 PDF CLI 매개변수 참조를 확인하십시오 .

5단계: 각 동시 작업에 고유한 LibreOffice 프로필을 지정합니다.

단일 변환은 종종 추가 프로필 구성 없이 작동하므로 확장성 문제를 숨길 수 있습니다. LibreOffice는 사용자 프로필에 상태를 저장하며 해당 프로필에 대한 쓰기 권한이 필요합니다. 병렬 작업자는 동일한 프로필 디렉터리를 두고 경쟁해서는 안 됩니다.

문서에 설명된 -env:UserInstallation=...부트스트랩 변수를 사용하여 작업에 비공개 프로필을 부여하세요.

docker run --rm   --mount type=bind,src="$(pwd)/input",dst=/input,readonly   --mount type=bind,src="$(pwd)/output",dst=/output   --tmpfs /tmp   libreoffice-headless:debian13   -env:UserInstallation=file:///tmp/lo-profile   --convert-to pdf   --outdir /output   /input/sample.docx

개인 임시 프로필은 수명이 짧은 컨테이너와 워커 풀에 특히 유용합니다. Docker 문서에는 tmpfs임시 메모리 파일 마운트에 대한 내용이 나와 있습니다. 하지만 수명이 긴 UNO 서비스를 실행해야 하는 경우에는 애플리케이션 설계에 따라 의도적인 영구 프로필 전략을 사용하고 접근을 직렬화하거나 격리해야 합니다.

6단계: 출력 파일이 실제로 존재하는지 확인합니다.

컨테이너가 종료된 후 호스트 출력 디렉터리를 확인하십시오.

ls -lh output/sample.pdf
file output/sample.pdf

종료 상태가 0이고 PDF 파일이 비어 있지 않은 경우 자동화 테스트를 위한 적절한 기준이 될 수 있지만, 완벽한 정확도 테스트는 아닙니다. 변환 API의 경우, 타임아웃을 설정하고 출력 파일이 없거나 크기가 예상보다 작은 경우 거부하도록 설정해야 합니다. 적절한 크기 임계값은 문서에 따라 다르므로, 데이터 세트를 측정하지 않은 상태에서 일반적인 고정 값을 사용하는 것은 피해야 합니다.

7단계: 하나의 프로세스를 맹목적으로 공유하지 말고 배치 작업을 신중하게 처리하세요.

LibreOffice는 `<filename>`을 사용하여 여러 입력 파일을 받을 수 있으며 --convert-to, 셸 루프를 사용하는 것도 간단합니다. 예를 들면 다음과 같습니다.

for f in input/*.docx; do
  docker run --rm     --mount type=bind,src="$(pwd)/input",dst=/input,readonly     --mount type=bind,src="$(pwd)/output",dst=/output     --tmpfs /tmp     libreoffice-headless:debian13     -env:UserInstallation=file:///tmp/lo-profile     --convert-to pdf     --outdir /output     "/input/$(basename "$f")"
done

처리량을 높이려면 LibreOffice를 반복적으로 시작하는 것이 비용이 많이 들 수 있습니다. 이때 --accept=...LibreOffice에서 수락자 생성 인터페이스로 설명하는 UNO를 사용하여 제어되는 영구 LibreOffice 프로세스를 고려해 볼 수 있습니다. 그러나 이렇게 하면 운영 모델이 변경됩니다. 프로세스 관리, 요청 격리, 시간 초과, 상태 점검, 그리고 문제가 있는 문서를 처리한 후 프로세스를 재활용하는 전략이 필요합니다. 처리량이 적거나 중간 정도인 경우에는 일회성 컨테이너 방식이 여전히 더 간단합니다.

8단계: 명령 성공 여부뿐만 아니라 시각적 충실도도 확인하십시오.

생성된 PDF 파일을 열어 예상 출력물과 비교해 보세요. 특히 페이지 나누기, 대체 글꼴, 삽입된 이미지, 수식, 머리글 및 바닥글, 차트, 스프레드시트 인쇄 영역, 프레젠테이션 텍스트 상자 등을 주의 깊게 살펴보세요. 헤드리스 모드는 그래픽 데스크톱 환경을 필요로 하지 않지만, 모든 Office 기능이 Microsoft Office와 동일하게 표시된다는 것을 보장하지는 않습니다.

자동 회귀 테스트를 위해서는 대표 문서들을 선별하여 페이지 수, 추출된 텍스트, 이미지 크기, 렌더링된 페이지 유사도와 같은 측정 가능한 속성을 비교하십시오. LibreOffice의 사소한 업데이트라도 PDF 메타데이터나 레이아웃의 세부 사항을 변경할 수 있으므로 임계값을 신중하게 검토해야 합니다.

변환이 실패할 경우: 가장 간단한 원인부터 해결하세요

1. 컨테이너는 종료되지만 아무런 출력도 나타나지 않습니다.

먼저 전달된 경로를 확인 --outdir하고 대상 마운트가 UID 10001에 쓰기 권한이 있는지 확인하십시오. Docker 바인드 마운트는 호스트 파일 시스템 권한을 컨테이너에 매핑합니다. 호스트 디렉터리의 소유자가 다른 UID이고 그룹 쓰기 권한이 없는 경우, 루트가 아닌 LibreOffice 프로세스가 출력을 생성하지 못할 수 있습니다.

2. LibreOffice에서 프로필 또는 잠금 문제가 발생했다고 보고합니다.

동시에 실행되는 작업마다 다른 -env:UserInstallation=file:///...경로를 사용하십시오. 여러 워커가 하나의 쓰기 가능한 프로필 디렉터리를 가리키도록 설정하지 마십시오. LibreOffice 문서에는 프로필 요구 사항과 UserInstallation재정의 방법이 모두 설명되어 있습니다.

3. PDF 파일은 생성되었지만 레이아웃이 잘못되었습니다.

내보내기 옵션을 변경하기 전에 글꼴을 확인하십시오. fc-list이미지 내부에서 필요한 글꼴이 제대로 표시되는지 확인하세요. 소스 파일이 매크로, 외부 데이터, 특이한 내장 객체 또는 독점 기능을 사용하는 경우, 헤드리스 변환 시 원래 애플리케이션과 정확히 일치하지 않을 수 있습니다. 임의의 명령줄 스위치를 추가하는 대신 코퍼스 기반 호환성 테스트를 사용하십시오.

4. 스프레드시트나 프레젠테이션은 변환되지 않습니다.

해당 LibreOffice 구성 요소가 설치되어 있는지 확인하십시오. libreoffice-noguiDebian 메타패키지에는 GUI를 지원하지 않는 Writer, Calc, Impress, Draw, Base 및 Math가 포함되어 있습니다. Writer만 포함된 더 작은 이미지를 의도적으로 빌드한 경우 XLSX 또는 PPTX 변환 시 필요한 구성 요소가 누락될 수 있습니다.

5. 읽기 전용 루트 파일 시스템으로 인해 시작이 실패합니다.

Docker를 이용한 보안 강화는 --read-only유용할 수 있지만, LibreOffice는 프로필 파일과 임시 파일을 저장할 쓰기 가능한 위치가 여전히 필요합니다. tmpfs해당 경로에 대해 명시적인 쓰기 가능 영역 또는 볼륨 마운트를 제공하십시오. Docker 컨테이너 실행 문서에서는 읽기 전용 루트 파일 시스템을 쓰기 가능 마운트와 결합하는 방법을 설명합니다.

보다 생산 지향적인 실행 명령

기본 흐름이 작동한 후에는, 더 엄격한 호출 방식을 통해 입력을 읽기 전용으로 유지하고, 임시 상태를 격리하며, 각 작업 후 컨테이너를 제거할 수 있습니다.

docker run --rm   --read-only   --mount type=bind,src="$(pwd)/input",dst=/input,readonly   --mount type=bind,src="$(pwd)/output",dst=/output   --tmpfs /tmp:rw,nosuid,nodev   --tmpfs /home/office:rw,nosuid,nodev   libreoffice-headless:debian13   -env:UserInstallation=file:///tmp/lo-profile   --convert-to pdf   --outdir /output   /input/sample.docx

이러한 보안 강화 방식이 모든 문서 유형에 적용되는지는 확장 기능, Java 종속 기능, 템플릿, 사전 및 기타 런타임 요구 사항에 따라 달라집니다. 컨테이너 전체를 쓰기 가능하게 만드는 대신, 검증된 워크로드에서 필요로 하는 경우에만 쓰기 가능한 경로를 추가하십시오.

자가 점검: 설치가 완료되었는지 확인하는 방법

컨테이너를 프로덕션 환경에 배포할 준비가 되었다고 판단하기 전에 다음 사항을 모두 확인하십시오.

• soffice --version배포하려던 LibreOffice 빌드를 보고합니다.
• 알려진 DOCX 파일이 컨테이너 종료 시 오류 없이 PDF로 변환됩니다.
• PDF 파일이 호스트에 0이 아닌 크기로 나타나며, 구문 분석 또는 열기가 가능합니다.
• 소스 디렉터리는 읽기 전용으로 마운트되며 변경되지 않습니다.
• 문서로 명시된 이유가 없는 한, 해당 프로세스는 루트 사용자가 아닌 일반 사용자 권한으로 실행됩니다.
• 대표 문서에서는 예상되는 글꼴을 사용하고 적절한 페이지 레이아웃을 유지합니다.
• 두 개의 동시 변환 작업은 각각 별도의 사용자 프로필을 사용하므로 서로 간섭하지 않습니다.
• 귀하의 애플리케이션은 시간 초과, 변환 오류 및 출력 누락을 빈 파일이나 오래된 파일을 반환하는 대신 실패로 처리합니다.

이러한 검사를 통과하면, 격리와 재현성을 중시하는 문서 변환 작업에는 헤드리스 LibreOffice 일회성 컨테이너가 적합합니다. 하지만 시작 지연 시간이 주요 비용이 되거나, 형식 변환보다는 API 수준의 문서 조작이 필요한 경우에는 관리형 영구 LibreOffice/UNO 서비스로 전환하고 해당 아키텍처를 별도로 테스트해야 합니다. Docker는 패키징과 격리 문제를 해결하지만, 애플리케이션이 실제로 처리하는 파일과 문서의 정확성을 검증해야 하는 필요성을 없애는 것은 아닙니다.