運用

Docker でのドキュメント変換

強化された GordonKit イメージ、同梱の LibreOffice、認証付き API、分離した Gotenberg renderer を使って、Docker Compose でドキュメント変換を実行します。

Profile の選択

すべての Compose service は明示的な選択制で、同じ GordonKit イメージを使います。ローカルのコマンドには cli、同梱 LibreOffice を使う API には standalone-lo、別の renderer を後段に置く API には gateway-gotenberg を使ってください。

CLI Profile

CLI モードは同梱の LibreOffice を使い、カレントディレクトリを /work にマウントします。API key は不要です。同じ 1 行のコマンドが Bash でも PowerShell でも動作します。

docker compose -f docker/compose.yaml --profile cli run --rm --build cli convert /work/report.docx --output /work/report.pdf --engine libreoffice --overwrite

単体構成の LibreOffice API

renderer を個別にスケールさせることよりも、シンプルな配備とローカル組版を重視する場合は、認証付き API と LibreOffice を 1 つのコンテナーで実行します。

# .env
GORDON_DOC_API_KEY=replace-me

docker compose -f docker/compose.yaml --env-file .env --profile standalone-lo up --build

Gotenberg Gateway

renderer の分離と独立したサービス健全性を重視する場合は、API を別の Gotenberg service と組み合わせて実行します。Compose は両サービスを gordon-doc network に接続し、Gotenberg が healthy になるまで待機します。Gotenberg URL を設定することはそのエンジンの明示選択を意味し、失敗しても暗黙に LibreOffice へフォールバックすることはありません。

docker compose -f docker/compose.yaml --env-file .env --profile gateway-gotenberg up --build

Bash からの API リクエスト

.env から配備者が管理する key を読み込み、エンジンを明示的に指定して PDF の応答を保存します。

set -a; . ./.env; set +a
curl --fail-with-body -H "Authorization: Bearer $GORDON_DOC_API_KEY" -H "Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document" -H "X-Filename: report.docx" --data-binary @report.docx "http://127.0.0.1:8000/conversions?engine=gotenberg" --output report-gb.pdf

PowerShell からの API リクエスト

PowerShell でも同じ .env を読み込み、Invoke-WebRequest でバイナリ応答を保存できます。standalone profile では engine=libreoffice を使ってください。

$env:GORDON_DOC_API_KEY = ((Get-Content .env | Where-Object { $_ -match '^GORDON_DOC_API_KEY=' }) -replace '^GORDON_DOC_API_KEY=', '')
$headers = @{ Authorization = "Bearer $env:GORDON_DOC_API_KEY"; 'X-Filename' = 'report.docx' }
Invoke-WebRequest -Uri 'http://127.0.0.1:8000/conversions?engine=gotenberg' -Method Post -Headers $headers -ContentType 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' -InFile .\report.docx -OutFile .\report-gb.pdf

サービスの停止

ローカルでの確認後は profile を停止します。生成された PDF はホストに残ります。

docker compose -f docker/compose.yaml --profile standalone-lo down
docker compose -f docker/compose.yaml --profile gateway-gotenberg down

公開イメージ

タグ付きリリースでは、gordonkit/gordon-doc-converter に linux/amd64 のイメージを 1 つ公開します。既定の entrypoint は CLI を実行し、api を渡すと HTTP service が起動します。再現性のある配備には明示的なバージョンタグを使ってください。

docker run --rm gordonkit/gordon-doc-converter:0.6.0 version
docker run --rm -p 8000:8000 -e GORDON_DOC_API_KEY=replace-me gordonkit/gordon-doc-converter:0.6.0 api

運用とセキュリティ

すべての profile は非 root ユーザー、読み取り専用の root filesystem、上限付きの一時ファイルシステム、no-new-privileges で実行されます。API profile には強度の高い key が必要で、本番の ingress ではリクエストサイズ制限と分散型のレート制限も適用してください。

python docker/smoke.py --token replace-me --docx sample.docx