DockerでKomgaをデプロイ:クロスプラットフォーム同期対応の自作マンガ・コミックサーバー構築

HomeLab tutorial - IT technology blog
HomeLab tutorial - IT technology blog

アプローチの比較:デジタルコミックコレクションのホスティング手法

深夜2時15分、タブレットで420MBの電子合本を開こうとしたところ、「504 Gateway Timeout」で画面が固まりました。サーバー側を確認すると、スワップ使用率は98%に達し、2基のCPUコアは100%に張り付き、バックグラウンドのインデクサーは30分前にクラッシュしていました。4TBものデジタルコミックやマンガを、一般的なメディアサーバーで動画ファイルと同じように扱っていれば、いずれ必ずこうした問題に直面します。

安定した環境に行き着くまでに、検証環境で以下の3つの構成をテストしました:

  • 一般的なメディアサーバー(コミックプラグイン導入のPlex / Jellyfin):これらのサーバーにおいて、書籍機能はあくまで「おまけ」に過ぎません。1ページ目を描画する前にアーカイブ全体を一時RAMバッファに解凍する仕組みになっています。Intel Celeron J4125やRaspberry Pi 4上で80話規模の長編コミックを開こうとすれば、LinuxのOOM(Out of Memory)キラーがほぼ即座に発動します。
  • ベアメタル構成のCalibre / Calibre-Web:CalibreはEPUBのメタデータ管理やISBN検索を軽快に処理します。しかし、NFSやSMB共有経由での同時読み取りが発生すると、SQLiteデータベースが頻繁にロックしてしまいます。また、Webリーダーでの見開き表示や右開きのマンガ閲覧には依然として難があります。
  • 専用OPDSエンジン(Komga / Kavita):Komgaはコミック、マンガ、グラフィックノベル専用に設計されています。CBZ、CBR、PDF、EPUBファイルをディスクから直接読み込みます。500MBのZipアーカイブをホストメモリ上に丸ごと解凍するのではなく、オンデマンドでWebPに変換されたページを1枚ずつストリーミング配信します。サムネイルのデコードはバックグラウンドのワーカープールで行われるため、閲覧中のセッションをロックすることもありません。

メリットとデメリット:Komga運用の実情

Spring BootマイクロサービスをDockerで運用するには、特にエントリークラスのハードウェアにおいて事前のチューニングが欠かせません。日常的な運用の実態は以下のとおりです:

メリット

  • 完全なクロスプラットフォーム読書進捗同期:OPDS-PSE(Page Streaming Extension)により、ブラウザやMihon、Tachiyomi、Chunky、Panelsなどのネイティブアプリ間で、読書位置、しおり、既読状態が即座に同期されます。
  • 非破壊的なライブラリ管理:適切に設定されたKomgaは、コミックディレクトリを厳格に読み取り専用として扱います。オリジナルのZipチェックサムを変更したり、メタデータXMLを書き換えたり、スキャン画像の順序を変更したりすることは一切ありません。
  • きめ細かなマルチユーザーACL:年齢制限や特定ジャンルタグのブラックリストを設定した個別のアカウントを家族向けに作成できます。ユーザーごとに未読カウンターや読書履歴が完全に独立して保持されます。

トレードオフと運用上の課題

  • JVMのメモリ消費量:KomgaはJava 21上で動作します。30MB程度のGo製バイナリとは異なり、計画的なヒープ割り当てが必要です。15,000話の初回ライブラリインポート時には、ガベージコレクションによって約800MBに落ち着くまで、メモリ使用量が1.2GB〜2.2GB程度まで簡単に膨らみます。
  • 厳格なフォルダ階層:適切なファイル整理が不可欠です。Komgaでは出版社/シリーズ名/第01巻.cbzやマンガ名/第01巻.cbzのような構造化されたフォルダ構成が求められます。単一のディレクトリに3,000ファイルをフラットに配置すると、データベースクエリの処理速度が極端に低下します。

推奨アーキテクチャ:クリーンな権限分離と高速キャッシュ

この構成の成否を分ける設計上のポイントは、「ユーザー権限の分離」と「アーカイブ展開時のRAMバッファリング」の2点です。コンテナをroot権限で実行すると、ホストディスク上にroot所有のサムネイルキャッシュが生成され、自動バックアップスクリプトやrsyncジョブの実行がブロックされてしまいます。

4TBのコレクションを安定稼働させている推奨アーキテクチャは以下のとおりです:

  • コンピュートノード:最低2 vCPU、4GB RAM(Ubuntu 24.04 LTSまたはDebian 12)。
  • ストレージ構成:コンテナ設定ファイルとSQLiteデータベースはNVMe SSD上に配置します。コミックファイル自体は専用のZFSプールまたはNASのNFSマウント上に保持します。
  • インメモリ一時バッファ:1GBのtmpfsボリュームを/tmpにマウントします。これによりページ展開がRAM上で直接処理され、SSDに対する1日あたり30GB〜50GBもの書き込み摩耗を防ぐことができます。

実践ガイド:Docker ComposeによるKomgaのデプロイ

ステップ1:ストレージディレクトリの準備と権限設定

専用メディアユーザーのUIDとGIDを確認します。root直下でのサービスデプロイは避けてください:

# 対象ユーザーのクレデンシャルを確認
id
# 出力例: uid=1000(sysadmin) gid=1000(sysadmin)

運用に必要なディレクトリを作成し、明示的に所有権を設定します:

sudo mkdir -p /opt/komga/config
sudo mkdir -p /mnt/storage/comics

# ユーザー1000にconfigディレクトリの所有権を付与
sudo chown -R 1000:1000 /opt/komga/config
sudo chmod -R 755 /opt/komga/config

ステップ2:本番用Docker Compose設定ファイルの作成

/opt/komga内にcomposeファイルを作成します:

cd /opt/komga
nano docker-compose.yml

以下の設定を記述します。コンテナの実行を非rootユーザー1000:1000に固定し、JVMヒープの上限を設定してメモリ肥大化を防止します:

services:
  komga:
    image: gotson/komga:latest
    container_name: komga
    restart: unless-stopped
    user: "1000:1000"
    environment:
      - TZ=Etc/UTC
      # ヒープメモリの制限: 初期512MB、上限2048MB
      - JAVA_TOOL_OPTIONS=-Xms512m -Xmx2048m
    volumes:
      # 設定ファイルとSQLiteデータベース
      - /opt/komga/config:/config
      # メディアアーカイブのライブラリ(読み取り専用としてマウント)
      - /mnt/storage/comics:/data:ro
      # ページ展開用の1GB揮発性RAMバッファ
      - type: tmpfs
        target: /tmp
        tmpfs:
          size: 1073741824
    ports:
      - "25600:25600"
    deploy:
      resources:
        limits:
          memory: 3072M

ステップ3:コンテナの起動とヘルスチェック

デタッチドモードでコンテナを起動します:

docker compose up -d

docker psでステータスが緑色の「Up」になっていても、Javaが正常に起動しているとは限りません。コンテナログを追跡し、データベースのマイグレーションとポートバインドが完了していることを確認します:

docker logs -f komga

Spring Bootの起動完了を示す以下のログ出力を確認します:

INFO  g.k.KomgaApplication - Started KomgaApplication in 7.842 seconds (process running for 8.611)

もしjava.io.FileNotFoundException: /config/database.sqlite (Permission denied)が発生した場合は、コンテナユーザーがバインドマウント先へ書き込めていません。docker compose downでスタックを停止し、sudo chown -R 1000:1000 /opt/komga/configを再実行してから、再度起動してください。

ステップ4:初期設定とライブラリの取り込み

  1. ブラウザでhttp://<サーバーIP>:25600にアクセスします。
  2. 強力なパスフレーズを設定し、プライマリ管理者アカウントを作成します。
  3. Server Settings > Librariesに移動し、Add Libraryを選択します。ライブラリ名を入力し、ルートパスに/dataを指定します。
  4. Options配下の「Analyze comic contents」を有効にします。これによりアスペクト比のインデックス作成、カラーページの検出、見開きページのタグ付けが自動的に実行されます。検証環境では、12,500個のCBZファイルの初回スキャンが約24分で完了しました。

ステップ5:OPDS-PSE経由でのモバイルクライアント連携

手動でファイルをエクスポートすることなく、スマートフォンやタブレット間で読書セッションを同期します:

  1. KomgaのWeb管理画面でAccount Settingsに移動し、個人のOPDS URL(例: http://<サーバーIP>:25600/opds/v1.2/catalog)をコピーします。
  2. AndroidならMihon、iOSならPanelsなどのモバイルリーダーアプリを開きます。
  3. そのカタログURLを使用して新しいOPDSソースを作成し、Komgaのアカウント情報を入力します。
  4. タブレットで1冊開いて45ページまで進め、KomgaのWebダッシュボードを確認してみてください。読書状態、読了率、タイムスタンプが即座に更新されているはずです。
Share: