gethomepage/homepage — 優良食堂詳しい解説

01 / 概要

何をするものか一文で言うと

ひとことで100以上のサービスと統合可能な、カスタマイズ性に優れた自己ホスト型ダッシュボード

gethomepage/homepage は、Docker やKubernetes上のサービスをまとめて表示する、静的生成型のセルフホストダッシュボードです。YAML設定ファイルまたはDockerラベルの自動検出でサービスを登録し、100種類以上のAPI連携ウィジェットを表示できます。Next.js製で、ビルド時に静的化されるため表示は高速です。

02 / 構造

どう動くのか中核のしくみ

読み方動きの流れを図と一緒にほどきました。

package.jsonからNext.js 16・React 19・dockerode・@kubernetes/client-nodeなどの依存が確認できます。設定はconfig/ディレクトリのYAMLファイル(services.yaml、settings.yamlなど)で行い、`src/skeleton`が初期テンプレートになります。Dockerfileはbuilderステージで`pnpm run build`を実行し、`.next/standalone`をrunnerステージにコピーする2段構成です。各サービスAPIへのリクエストはNext.jsのAPIルート経由でプロキシされ、APIキーをブラウザに露出させない設計です。`docker-entrypoint.sh`がコンテナ起動時にPUID/PGIDでユーザーを調整し、`node server.js`でHOSTNAME=::、PORT=3000のスタンドアロンサーバーを起動します。認証機能はnext-authに依存し、HOMEPAGE_AUTH_ENABLEDやHOMEPAGE_AUTH_SECRETなどの環境変数で有効化するオプトイン方式です。HOMEPAGE_ALLOWED_HOSTSでHostヘッダーを検証し、一部の攻撃を防ぐ仕組みも入っています。

03 / 体験

入れるとこんな体験になりますギット飯が実際にたどった順序

所要ギット飯が実際に導入・実行しながらたどった順序です。

STEP 01
docker composeでHOMEPAGE_ALLOWED_HOSTSを自分のホスト名に設定し、`/app/config`と`/var/run/docker.sock`をマウントしてコンテナを起動します。
STEP 02
初回起動時は`src/skeleton`相当のサンプルconfig(services.yaml、widgets.yamlなど)が生成され、それを編集してサービス一覧を書きます。
STEP 03
ブラウザでport 3000にアクセスすると、静的生成されたダッシュボードに登録したサービスのアイコンやステータスが表示されます。
STEP 04
Dockerラベルを既存コンテナに付与すると、再起動なしで自動的にサービスカードが増えることを確認できます。
STEP 05
HOMEPAGE_AUTH_ENABLEDを有効にすると、初回アクセス時にパスワードまたはOIDCログイン画面が挟まることを体験できます。
STEP 06
pnpm testを実行すると、vitestによる_appや_documentなどのユニットテストが走り、CIと同じ検証結果を手元でも確認できます。

04 / 成果物

何が手に入るのか導入後に手元に残るもの

YAMLとDockerラベルだけで、自宅サーバーやNAS上の各種サービス(Sonarr、Jellyfin、Grafanaなど)を1画面にまとめたダッシュボードが得られます。APIキーはサーバー側プロキシに隠れるため、フロントに露出しない構成が手に入ります。加えて、テストコードとDocker/K8s向けの公式イメージが揃っているため、そのまま本番運用に組み込める状態です。

05 / 注意

ここは先に知っておいてください先に知っておくとよいこと

正直なところ誰にでも合うとは言いにくいところです。

公開ネットワークからアクセスする場合はリバースプロキシやVPNでの認証・TLSが前提で、内蔵認証だけでは不十分と明記されています。

パスワードログインにはアプリ側のレート制限がなく、fail2ban相当の対策を自分で用意する必要があります。

HOMEPAGE_ALLOWED_HOSTSの設定を誤るとHostヘッダー検証で弾かれ、ログを見ながら調整する作業が発生します。

06 / 結論

ギット飯の結論食べてみる価値のある一膳か

ギット飯の最終判断優良食堂

自宅や社内LANで複数のセルフホストサービスを1画面にまとめたい人には向いています。DockerラベルとYAMLの二重構成、standaloneビルドのDockerfile、next-authベースの認証コードが実在するため、README記載の機能は構造的に裏付けられています。ただし公開運用時の認証強度は自前設定に依存するため、そこは自分の環境に合わせて確認したうえで採用するのが安全です。