独自のイメージレジストリ

独自のレジストリが必要になる場面、パスワードと証明書による設定方法、消費するディスク容量、古いイメージの溜まり場にしないための方法について説明します。

更新日 2026年8月23日

レジストリとはイメージの保管庫です。独自のレジストリが必要になるのは次の3つの場合です。イメージが非公開で自社のインフラから出してはいけない場合、ビルドが頻繁に発生し外部のダウンロード制限が邪魔になる場合、同じものを複数のマシンにデプロイする場合です。

シンプルな選択肢: registry:2

services:
  registry:
    image: registry:2
    restart: unless-stopped
    environment:
      REGISTRY_AUTH: htpasswd
      REGISTRY_AUTH_HTPASSWD_REALM: Registry
      REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd
      REGISTRY_STORAGE_DELETE_ENABLED: "true"
    volumes:
      - ./data:/var/lib/registry
      - ./auth:/auth:ro
    ports:
      - "127.0.0.1:5000:5000"

パスワードは次のように作成します。

mkdir -p auth
docker run --rm --entrypoint htpasswd httpd:2 -Bbn deploy 'long-password' > auth/htpasswd
docker compose up -d

ポートを外部に公開しないでください。証明書を導入したWebサーバーをレジストリの前に置きます。DockerはサードパーティのレジストリをHTTP経由で扱うことを拒否します。当然のことで、レジストリを通じて実行可能なコードがお使いのマシンに届くからです。

操作

docker login registry.example.com
docker tag myapp:1.5.0 registry.example.com/myapp:1.5.0
docker push registry.example.com/myapp:1.5.0
docker pull registry.example.com/myapp:1.5.0

curl -u deploy https://registry.example.com/v2/_catalog
curl -u deploy https://registry.example.com/v2/myapp/tags/list

docker login の後、認証情報は ~/.docker/config.json に平文で保存されます（base64は暗号化ではありません）。ビルドマシンでは、読み取り専用権限を持つ別のアカウントを作成してください。

サイズ制限もクリーンアップもないレジストリは、ディスクを最も手早く満杯にする方法です。ビルドのたびにレイヤーが追加され、タグを削除しても容量は解放されません。ガベージコレクションが必要です。40 GBのVDS-1では、活発なプロジェクトのレジストリが数週間でディスクを埋め尽くします。

クリーンアップ

タグの削除とそれに続くガベージコレクション:

docker compose exec registry registry garbage-collect \
  --delete-untagged /etc/docker/registry/config.yml

ガベージコレクションの実行中はレジストリを停止する必要があります。そうしないと、同時進行のプッシュでレイヤーが失われる可能性があります。

docker compose stop registry
docker compose run --rm registry registry garbage-collect --delete-untagged /etc/docker/registry/config.yml
docker compose start registry

これを週に1回のスケジュールジョブとして設定し、ディスク容量を監視してください。

代替案: Gitサーバーに同梱されたレジストリ

すでにForgejoまたはGiteaをセットアップしている場合、これらのにはDockerイメージを含むパッケージストアが組み込まれています。別のサービスは不要です。アクセスは同じアカウントを通じて行われ、イメージはコードの隣に表示されます。小規模なプロジェクトでは、単独の registry:2 よりも便利です。

よくある間違い

レジストリが認証なしで公開されている。 これを介して、誰かがお客様自身の本番マシンにデプロイされるイメージを仕込むことができます。
バージョンの代わりに latest タグを使用する。 レジストリは再現性の源ではなくなります。何がデプロイされているのか不明確になります。コンテナの更新を参照してください。
データベースと同じディスクにストレージを置く。 プッシュの急増がディスク帯域を食い尽くし、本番サービスを遅くします。ディスク速度を参照してください。
./data ディレクトリがバックアップに含まれていない。 手元にソースがないすべてのイメージを失います。バックアップすべきものを参照してください。