ZimaOS App StoreでのPaperless-ngxのインストールは終盤に失敗しました。最初はGitHub Container RegistryからTikaイメージを取得する際の未承認エラーが発生し、その後はレジストリミラーのDNS解決に失敗しました。この組み合わせにより、このスレッドは単に「Paperlessが壊れている」という話より複雑です。失敗したのはオプションのTikaサービス／イメージの経路であり、試行ごとにレジストリエンドポイント自体も変わっていました。
公開スレッドでは、ZimaOS App Storeの修正方法が確認されることはありませんでした。あるユーザーはTikaイメージをApacheのイメージに変更し、インストールを100%まで進めましたが、スタックは起動しませんでした。現在のPaperless-ngxドキュメントでは、より明確な方法が案内されています。保守されているDocker Composeテンプレートを使用し、対象のドキュメント形式が必要な場合にのみTika／Gotenbergのバリアントを有効にします。
最初の失敗はGHCRの認証エラーだった
最初のエラーは約80%の時点で発生しました。
Head "https://ghcr.io/v2/paperless-ngx/tika/manifests/2.9.1-minimal": unauthorizedローカルのDockerイメージを削除して再インストールしても結果は変わらなかったため、単純に古いローカルイメージが原因だったとは考えにくい状況です。
次の試行ではDNS解決に失敗した
2日後、エラーはレジストリミラーのホスト名に対するDNSルックアップ失敗へと変わりました。そのため、コミュニティの回答者は、名前解決、基本的なHTTPS接続、DNSフィルタリング、VPN／プロキシの動作、手動でのイメージ取得を確認するよう提案しました。
これらはコミュニティによる診断であり、IceWhaleが確認した根本原因ではありません。
現在のPaperless-ngxではTikaはオプション
現在のPaperless-ngxドキュメントによると、TikaとGotenbergは、DOC／XLSX／ODTなどのOffice文書やメール解析に使用するオプションサービスです。これらの形式が不要であれば、Tikaを有効にする必要はありません。
必要な場合は、古いApp Storeのイメージ参照ではなく、TikaとGotenbergを含む保守済みのComposeバリアントを使用してください。
現在のアップストリームDocker Composeを基準にする
現在のPaperless-ngxセットアップガイドでは、ほとんどのユーザーにDockerを推奨し、保守されているComposeファイルを提供しています。新規インストールではPostgreSQLの使用が推奨され、Tika対応テンプレートも別途用意されています。
ZimaOS App Storeのパッケージが古い場合や、利用できない補助イメージを参照している場合は、現在のPaperless-ngx Docker Composeによるインストール方式を使用してください。
Tikaイメージだけを変更しても十分とは限らない
ある参加者はTikaイメージをapache/tika:latestに置き換えました。インストールは100%まで進みましたが、起動後もアプリケーションは失敗しました。
この結果は重要です。Paperlessでは、サービスエンドポイント、機能フラグ、Gotenbergとの連携がCompose設定と一致している必要があります。コンテナイメージの差し替えだけでは、スタック全体の移行が完了したとは限りません。
Paperlessの永続データはメインストレージ領域に置く
Paperlessでは、取り込んだ文書、サムネイル、OCRデータ、検索インデックス、データベースによって容量が増加します。現在のZimaOSでは、容量を多く使用するアプリをインストールする前に、アプリデータをシステムドライブから移動することが推奨されています。
現在のZimaOSアプリストレージパスの方式は、Paperlessのデータ容量がDockerイメージのサイズを大幅に超える可能性があるため、特に重要です。
消費フォルダーには権限設定が必要
現在のPaperless-ngxドキュメントでは、コンテナがホストのバインドマウントフォルダーに書き込めるよう、USERMAP_UIDとUSERMAP_GIDを設定できます。スタックのインストールは完了したものの文書を取り込めない場合は、レジストリの問題に戻るのではなく、これらの値とホストフォルダーの権限を確認してください。
レジストリミラーのホスト名をPaperlessアプリケーションと混同しない
2つ目のエラーでは、メインのghcr.ioエンドポイントではなく、ミラー形式のホスト名が参照されていました。この違いは重要です。アプリケーションパッケージ自体が完全に正しくても、設定されたイメージミラー、DNSサーバー、または地域別レジストリ経路が利用できない場合があります。
アップストリームレジストリからの手動取得には成功するのに、App Storeが壊れたミラーを使い続ける場合、問題はPaperlessそのものではなく、パッケージまたはレジストリルーティングの層にあります。
イメージ取得の失敗とコンテナ起動の失敗を分けて考える
最初の試行では、必要なイメージをすべて取得し終える前に停止しました。その後のApache Tikaの実験では、インストールは100%まで進みましたが、起動後に失敗しました。これは異なる失敗段階であり、それぞれに異なる証拠が必要です。
- 取得段階：レジストリ認証、DNS、ミラーの可用性、イメージタグ。
- 起動段階：環境変数、データベース接続、Tika／Gotenbergのエンドポイント、ボリューム、権限、ヘルスチェック。
App Storeのスタックを置き換える前に、動作中のPaperlessをバックアップする
Paperlessをすでに使用している場合は、補助サービスを修正するためだけにComposeテンプレートを切り替える前に、文書とデータベースを必ず保護してください。現在のアップストリーム版Paperlessには、バックアップと移行専用のエクスポーターが含まれています。
新規インストールなら、保守されているアップストリームのComposeファイルから始める方が簡単です。既存のインストールでは、スタックを書き換える前に現在のデータベースとメディアパスを保持してください。
Paperless-ngxインストールに関するFAQ
2025年の失敗は、DNSの問題だと確定したのですか？
いいえ。スレッドでは認証エラーとDNSエラーの両方が示されており、公式の最終診断は投稿されていません。
すべてのPaperless-ngxインストールでTikaが必要ですか？
いいえ。Tikaはオプションで、主にOffice文書とメール解析に必要です。
apache/tikaに切り替えれば、元のケースは完全に解決しましたか？
いいえ。あるユーザーはインストールを100%まで進めましたが、アプリケーションは起動しませんでした。
