Dockerコンテナ内でLibreOfficeをヘッドレスモードで実行する方法

サーバー側でよくある問題は、一見単純に見えます。アプリケーションが DOCX、XLSX、ODT、または PPTX ファイルを受け取り、PDF を返す必要があるのですが、ホスト上でデスクトップ セッションを実行してはなりません。ホストにオフィス スイート一式を直接インストールすると、デプロイメントの再現が難しくなります。LibreOffice はグラフィカル インターフェイスなしで実行でき、Docker は変換ランタイムを分離できますが、信頼性の高い結果を得るには、--headlessコマンドに何かを追加するだけでは不十分です。

ほとんどの失敗の実際的な原因は予測可能です。イメージに必要なLibreOfficeコンポーネントが含まれていない、コンテナがユーザープロファイルを書き込めない、バインドマウントされたファイルのアクセス許可が間違っている、フォントが不足している、2つのジョブが同じプロファイルを共有している、または出力ディレクトリに書き込み権限がない、といったことが考えられます。このガイドでは、最もシンプルな動作するコンテナから始め、繰り返しドキュメント変換ができるようにコンテナを強化していきます。

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-noguiが便利な出発点となります。Debian では、主にスクリプト作成を目的とした非 GUI メタパッケージとして説明されているからです。Writer ドキュメントのみを変換する場合は、 と必要な他の非 GUI コンポーネントのみをインストールすることで、依存関係を減らすことができますlibreoffice-writer-nogui。

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"]

フォントパッケージは見た目だけのものではありません。Office文書では、最小限の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：入力ディレクトリと出力ディレクトリを別々に準備する

ホストディレクトリを2つ作成します。入力側は読み取り専用で構いませんが、出力側はコンテナユーザーが書き込み可能である必要があります。

mkdir -p input output
cp sample.docx input/

Docker は--mountバインドマウントの構文を推奨しています。また、バインドマウントはデフォルトで書き込み可能であるため、ソースディレクトリを明示的に読み取り専用に設定することは有効な安全策であるとドキュメントに記載されています。Dockerのバインドマウントに関するドキュメントを参照してください。

ステップ4：1つのドキュメントを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 から 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

終了ステータスがゼロで、かつPDFファイルが空でないことは、妥当な自動化ゲートではありますが、完全な忠実度テストではありません。変換APIの場合は、タイムアウトを設定し、出力ファイルが欠落している場合や、予想外に小さい場合は出力を拒否するようにしてください。適切なサイズしきい値はドキュメントによって異なるため、コーパスを測定していない限り、普遍的なハードコードされた数値を使用することは避けてください。

ステップ7：1つのプロセスを盲目的に共有するのではなく、バッチを慎重に処理する

LibreOfficeは、複数の入力ファイルを受け入れることができ--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によって所有され、グループによる書き込みが許可されていない場合、非rootのLibreOfficeプロセスは出力を作成できない可能性があります。

2. LibreOfficeでプロファイルまたはロックの問題が報告される

同時実行ジョブごとに異なる-env:UserInstallation=file:///...パスを使用してください。複数のワーカーを1つの書き込み可能なプロファイルディレクトリに指定しないでください。LibreOfficeには、プロファイル要件とUserInstallationオーバーライドの両方に関するドキュメントがあります。

3. PDFファイルは作成されたが、レイアウトが間違っている。

エクスポートオプションを変更する前にフォントを確認してください。fc-listイメージ内で必要なフォントが表示されていることを確認してください。ソースファイルがマクロ、外部データ、特殊な埋め込みオブジェクト、または独自機能に依存している場合、ヘッドレス変換では元のアプリケーションが完全に再現されない可能性があります。ランダムなコマンドラインスイッチを追加するのではなく、コーパスベースの互換性テストに移行してください。

4. スプレッドシートやプレゼンテーションは変換されません

対応するLibreOfficeコンポーネントがインストールされていることを確認してください。Debianlibreoffice-noguiメタパッケージには、Writer、Calc、Impress、Draw、Base、Mathが含まれていますが、GUIはサポートされていません。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ファイルはホスト上でサイズがゼロ以外で表示され、解析または開くことができます。
• ソースディレクトリは読み取り専用でマウントされ、変更されません。
• 特別な理由が文書で明記されていない限り、このプロセスは非rootユーザーとして実行されます。
• 代表的な文書では、想定されるフォントが使用され、適切なページレイアウトが維持されます。
• 2つの同時変換はそれぞれ別のユーザープロファイルを使用するため、互いに干渉しません。
• アプリケーションは、タイムアウト、変換エラー、出力の欠落を、空のファイルや古いファイルを返すのではなく、失敗として扱います。

これらのチェックに合格すれば、ワンショットのヘッドレスLibreOfficeコンテナは、分離性と再現性を重視する文書変換ジョブに最適です。起動時の遅延が主なコストとなる場合、またはフォーマット変換ではなくAPIレベルの文書操作が必要な場合は、監視付きの永続的なLibreOffice/UNOサービスに切り替えて、そのアーキテクチャを別途テストしてください。Dockerはパッケージングと分離の問題を解決しますが、アプリケーションが実際に処理するファイルに対して文書の整合性を検証する必要性を排除するものではありません。