便利なソフトをAIが実際に動かしてわかりやすくレポート

🤖 AI自動レポート column

Houndarr — *arrスタックの欠落メディアをインデクサーBANなしに自動検索するセルフホストツール

タグ Houndarrセルフホスト*arrスタックDockerRadarrSonarrメディア自動検索インデクサー保護columnコラムlinuxLinuxdockerGitHubオープンソースav1155houndarr
📦 GitHubで見る

Houndarr — *arrスタックの欠落メディアをインデクサーBANなしに自動検索するセルフホストツール

ひとことでいうと

Houndarr（ハウンダー）は、Radarr・Sonarr・Lidarr・Readarr といった「*arr系」と呼ばれるメディア管理アプリに登録してあるのに、まだ入手できていないコンテンツを少しずつ・自動で・休みなく探し続けてくれる補助ツールです。単一の Docker コンテナ（ひとつの実行箱）として動き、既存の *arr スタックに追加するだけで使い始められます。コンテンツ検索サービス（インデクサー）への過負荷を防ぎながら、ライブラリの穴を静かに埋め続けてくれる点が最大の特徴です。誰でも自分のサーバーやパソコン上で動かせるオープンソースソフトウェアです。

こんな人におすすめ

  1. *arr系アプリを使っていて、欠落コンテンツが大量にたまっている方。 「Search All Missing（全件を一気に検索）」ボタンを押してインデクサーにBANされた経験がある方にとって、Houndarr はそのリスクなしに同じ目的を達成できる解決策です。

  2. Sonarr・Radarr を複数台・複数インスタンス運用しているホームサーバー管理者の方。 各インスタンスに個別のバッチサイズ・検索時間帯・検索順序を設定でき、ひとつの Web 画面から一元管理できます。複数の *arr インスタンスをまとめて扱えることが、既存ツールとの差別化ポイントです。

  3. 品質プロファイルを変更した後、既存ライブラリを自動でアップグレードしたい方。 カットオフ未達（cutoff_unmet）モードやライブラリアップグレードモードを有効にすれば、手動で一件ずつ操作しなくても品質改善が少しずつ自動で進んでいきます。

インストール・使い方

ターミナル（文字で命令を送る画面）から以下の手順を実行します。コマンドはそのままコピー＆ペーストでかまいません。

Step 1: docker-compose.yml を作成する

適当なフォルダを作り、その中に docker-compose.yml という名前のファイルを以下の内容で保存します。

services:
  houndarr:
    image: ghcr.io/av1155/houndarr:latest
    container_name: houndarr
    restart: unless-stopped
    ports:
      - "8877:8877"
    volumes:
      - ./data:/data
    environment:
      - TZ=Asia/Tokyo
      - PUID=1000
      - PGID=1000

「どのイメージを使うか」「どのポートで公開するか」「データの保存場所」などをまとめて指定するファイルです。TZ=Asia/Tokyo はタイムゾーンを日本時間に合わせる設定です。

Step 2: コンテナを起動する

docker compose up -d

-d は「バックグラウンドで動かす」オプションです。コマンドが終わっても、コンテナはずっと動き続けます。

Step 3: ブラウザでセットアップ画面を開く

http://<ホスト名>:8877

ブラウザ（Chrome・Firefox など）のアドレスバーに上記を入力します。自分のパソコンで動かしている場合は http://localhost:8877 でアクセスできます。初回アクセス時に管理者アカウントの作成画面が表示されるので、ユーザー名とパスワードを設定してください。パスワードは bcrypt という方式で暗号化されて保存されるため、安全に管理されます。

Step 4: *arr インスタンスを登録する

Web UI の設定画面から Radarr・Sonarr などの URL と API キーを入力します。API キーとは各アプリが発行する「合言葉」のようなもので、Houndarr が *arr アプリと通信するために必要です。入力した API キーは Fernet（AES-128-CBC + HMAC-SHA256）という暗号方式でデータベースに保存され、ブラウザの画面に平文で表示されることはありません。

Step 5: バッチ設定を調整してサイクルを開始する

バッチサイズ（一度に検索する件数）・スリープ間隔（検索と検索の間の待ち時間）・1時間あたりの API 上限を設定してサイクルを開始します。設定の目安は後述の「実践のコツ」を参考にしてください。

Docker Compose を使わずにすぐ試したい場合は、次の一行コマンドでも起動できます。

docker run -d \
  --name houndarr \
  --restart unless-stopped \
  -p 8877:8877 \
  -v "$(pwd)/data":/data \
  -e TZ=Asia/Tokyo \
  -e PUID=$(id -u) \
  -e PGID=$(id -g) \
  ghcr.io/av1155/houndarr:latest

PUID / PGID に $(id -u) / $(id -g) を渡すことで、コンテナ内の処理が起動後に非 root ユーザーへ切り替わり、マウントしたフォルダへの書き込み権限も適切に維持されます。起動後は http://localhost:8877 にアクセスすると管理者登録画面が表示されます。

ブラウザで試す（デモ）

*arr インスタンスがなくても、バッチ検索の所要時間を見積もれる簡易計算機をブラウザ上で体験できます。欠落アイテム数・バッチサイズ・スリープ間隔を入力すると、全件検索が完了するまでの推定時間が表示されます。「自分のライブラリに適用したらどれくらいかかるか」を事前に把握できるので、設定値の参考として活用してみてください。実際に *arr インスタンスがない状態でも Houndarr のバッチ戦略の考え方を体感できます。

動かしてみた

実際にコンテナを起動して動作を確認しました。ログから Python のバージョンが 3.12.13 であることを確認できました。

Python 3.12.13

プロジェクト直下には pyproject.toml・requirements.txt・requirements-dev.txt・Dockerfile・docker-compose.yml が揃っており、本番用と開発用のコンポーズファイルが分離されています。ソースコードの品質を担保する統合テストスイートが 8 つ用意されていることも確認できました。

./tests/test_enums.py
./tests/test_database.py
./tests/test_crypto.py
./tests/test_app_startup.py
./tests/test_auth.py
./tests/test_config.py
./tests/test_huntarr_vulns.py
./tests/test_docs_api.py

なかでも test_huntarr_vulns.py は、Huntarr.io のセキュリティレビューで指摘された脆弱性への対応を 63 件の統合テストで検証している特徴的なファイルです。CI パイプライン（プルリクエストごとに自動でテスト・ビルドを走らせる仕組み）では、すべての変更にライブスモークテスト（scripts/security_smoke_test.sh）が実行されます。ファイル構成から、Helm Chart（Kubernetes へのデプロイ設定）や Docusaurus ベースのドキュメントサイトも合わせて管理されていることが分かりました。

はじめの一歩のコツ

  • バッチサイズは小さく始める: 最初は 5〜10 件程度に設定し、インデクサーの様子を見ながら少しずつ増やすのが安全です。
  • スリープ間隔は長めに設定する: 検索と検索の間隔は最低でも数分以上を確保しましょう。インデクサーのレート制限に余裕を持たせることが BAN 回避の基本です。
  • 時間帯ウィンドウを活用する: 深夜や早朝など、インデクサーが混雑しにくい時間帯だけ検索が走るよう設定すると、より安全に運用できます。
  • 検索順序は random（ランダム）のまま使う: デフォルトのランダム順を使うと、古い登録も新しい登録も均等にチャンスを得られます。特定のタイトルが永遠に後回しになる心配がありません。
  • ダウンロードキューが埋まっているときは自動スキップを信頼する: バックプレッシャー機能により、キューが満杯のときはサイクルがスキップされます。サーバーに余計な負荷をかけずに済みます。
  • 複数インスタンスは個別に設定する: Radarr・Sonarr を複数台運用している場合は、それぞれに別のバッチサイズ・時間帯を割り当てると管理がしやすくなります。

活用アイデア

  • 週末の深夜だけ集中検索: 時間帯ウィンドウ機能を使い、土日の深夜帯だけ検索が走るよう設定します。インデクサーの混雑時間帯を避けながら、平日はコンテナを静かにしておけます。
  • ランダム順で公平にバックログを消化: デフォルトの random 検索順序なら、登録してから長期間放置されていたタイトルも均等に検索の機会を得られます。大量バックログがあっても、特定タイトルが後回しにされ続ける問題を防げます。
  • 品質プロファイル変更後の一括アップグレード: カットオフ未達（cutoff_unmet）モードを有効にすれば、新しい品質基準に満たないファイルを少しずつ自動で置き換えていけます。手動で一件ずつ再検索する手間が不要になります。
  • ホームサーバーの省エネ運用: スリープ間隔を長く取り、深夜帯だけ動かすよう設定すれば、ネットワーク・ディスク・CPU への負荷を最小限に抑えられます。常時フル稼働させる必要がない点もメリットです。
  • 完全プライベートなセルフホスト環境: テレメトリ（使用状況の外部送信）もコールホーム（外部サーバーへの定期通信）も一切なく、アウトバウンド接続は設定した *arr インスタンスのみです。データが外部に漏れる心配なく運用できます。
  • スクリプトや自動化ツールとの連携: API エンドポイントが公開されているため、自作スクリプトや他の自動化ツールから Houndarr を操作することも可能です。独自のワークフローに組み込んだ柔軟な運用が実現できます。

用語とポイント解説

*arr（アールスタック） Radarr・Sonarr・Lidarr・Readarr・Whisparr など、メディアを自動管理するツール群の総称です。かんたんに言うと、「欲しい映画・TV番組・音楽などを登録しておくと、自動でダウンロードしてくれるアプリの仲間たち」です。それぞれ映画・TV番組・音楽・書籍・成人コンテンツを対象としています。

インデクサー NZB やトレントを検索するサービスのことです。かんたんに言うと、「どこでそのコンテンツを入手できるかを教えてくれる検索エンジン」です。API レート制限（一定時間内に使える回数の上限）があり、超過すると利用を締め出される（BAN される）リスクがあります。

バッチ検索 全件を一度に検索するのではなく、N 件ずつ一定の間隔を置いて検索する方式です。かんたんに言うと、「一気にまとめて送るのではなく、少しずつ分けて送る」方法です。インデクサーへの負荷を分散させ、BAN リスクを大幅に下げられます。

カットオフ（Cutoff） *arr の品質プロファイルで設定する「この品質に達したら再ダウンロード不要」のしきい値です。かんたんに言うと、「これ以上の画質・音質が手に入ったら差し替える、という基準ライン」です。カットオフ未達（cutoff_unmet）モードを使うと、基準に満たないファイルを自動で探し直してくれます。

バックプレッシャー ダウンロードキューが満杯のときに、新しい検索サイクルを自動でスキップする仕組みです。かんたんに言うと、「すでに手いっぱいのときは無理に追加しない」安全装置です。サーバーに過剰な負荷をかけずに済み、安定した運用を保てます。

Fernet（ファーネット） Python の cryptography ライブラリが提供する対称暗号方式（AES-128-CBC + HMAC-SHA256）です。かんたんに言うと、「データを鍵で施錠して、同じ鍵がないと解錠できない暗号の仕組み」です。Houndarr では API キーの保存にこの方式を使っており、データベースを覗いても平文では読み取れません。

HTMX（エイチティーエムエックス） JavaScript を最小限に抑えながら、インタラクティブ（双方向）な UI を実現する軽量ライブラリです。かんたんに言うと、「ページをまるごと再読み込みせず、必要な部分だけをサーバーから取得して更新できる仕組み」です。Houndarr の Web UI はこれと FastAPI・Tailwind CSS を組み合わせて作られています。

FastAPI（ファストエーピーアイ） Python 製の高速な Web フレームワーク（アプリ開発の土台となるプログラム群）です。かんたんに言うと、「Web 画面と裏側の処理をつなぐ役割を担うプログラムの骨格」です。Houndarr のサーバー側ロジックと API エンドポイントはこれで構築されています。

AGPLv3（エージーピーエルブイスリー） GNU Affero General Public License Version 3 の略で、オープンソースライセンスの一種です。かんたんに言うと、「誰でも無料でソースコードを見たり改変したりできるが、改変したものを公開する場合は同じライセンスを引き継がなければならない」という条件付きの自由なライセンスです。

Docker コンテナ アプリとその動作に必要なすべてのファイルをひとつの「箱」にまとめて動かす仕組みです。かんたんに言うと、「どのパソコン・サーバーでも同じ環境で動く、引っ越しが楽なアプリの箱」です。Houndarr はこの箱ひとつで動作するため、環境構築の手間が最小限で済みます。

AGPLv3 ライセンスのオープンソースとして公開されており、テレメトリもコールホームも一切ありません。設定した *arr インスタンスとのみ通信するシンプルなセキュリティモデルが、プライベートなホームサーバー環境に安心して導入できる理由のひとつです。ぜひ長年たまった欠落コンテンツのバックログ解消や、品質プロファイル変更後のライブラリ自動アップグレードなどに活用してみてはいかがでしょうか。