Docker プライベートレジストリ構築ガイド｜`registry`コンテナで自前運用

社内限定のイメージ配布、Docker Hub の Rate Limit 回避、インターネット非接続の閉域運用——これらのケースでは自前のプライベートレジストリを立てる選択肢があります。Docker公式の registry（Distribution プロジェクト）を使えば、たった1コマンドで始められます。

💡 この記事のゴール
① registry:2 コンテナでローカルレジストリ起動
② push / pull の疎通確認
③ TLS（HTTPS）化と Basic認証
④ ストレージの永続化とGC
⑤ 選択肢：registry コンテナ vs Harbor など

1. なぜプライベートレジストリ？

理由	内容
機密コードの配布	外部に公開したくない社内アプリ
Docker Hub Rate Limit 回避	CI で連続pullしても枯れない
閉域運用（オンプレ・インターネット無し）	外部レジストリに接続不可の環境
pull 高速化	同一LAN内から取得、ネット帯域節約
厳格な監査要件	自社完結で追跡可能

2. 最速で立ち上げる

# registry コンテナを起動（ポート5000がデフォルト）
docker run -d --name registry -p 5000:5000 registry:2

# 動作確認
curl http://localhost:5000/v2/_catalog
# → {"repositories":[]}  ← まだ何もない状態

registry:2 は Docker 社が配布している公式イメージ。V1は廃止され、現在は V2（Distribution）のみ使用されます。

3. push / pull の流れ

3-1. 既存イメージを自前レジストリに push

# Docker Hub から取得
docker pull nginx:1.27

# 自前レジストリ向けにタグ付け（localhost:5000/xxx）
docker tag nginx:1.27 localhost:5000/my-nginx:1.27

# push
docker push localhost:5000/my-nginx:1.27

3-2. 別マシンから pull する

# LAN 上のレジストリから
docker pull registry.example.local:5000/my-nginx:1.27

⚠️ HTTP のままだと Docker がエラーを出す
Docker は既定で HTTPS を要求します。HTTPで試験的に使うときは、daemon.json の insecure-registries に追加が必要：
{"insecure-registries": ["registry.example.local:5000"]}
Dockerデーモン再起動後、HTTP通信を許可します。本番では必ずTLS化してください（次セクション）。

4. TLS（HTTPS）化

# 証明書を準備（Let's Encrypt、または社内CA発行）
# certs/ に domain.crt と domain.key を置く

docker run -d --name registry \
  -v "$(pwd)/certs":/certs \
  -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
  -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
  -p 443:443 \
  -e REGISTRY_HTTP_ADDR=0.0.0.0:443 \
  registry:2

リバースプロキシ（nginx / Caddy / Traefik）を前段に置き、TLS終端させるのが実戦的。証明書ローテーションやルーティングをプロキシ側で管理できます。

5. Basic認証

# htpasswd でユーザー作成（bcrypt推奨）
mkdir auth
docker run --rm --entrypoint htpasswd httpd:2 \
  -Bbn myuser mypassword > auth/htpasswd

# 認証付きで起動
docker run -d --name registry \
  -v "$(pwd)/auth":/auth \
  -v "$(pwd)/certs":/certs \
  -e "REGISTRY_AUTH=htpasswd" \
  -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \
  -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \
  -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
  -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
  -p 443:443 \
  -e REGISTRY_HTTP_ADDR=0.0.0.0:443 \
  registry:2

# クライアント側で login
docker login registry.example.local
Username: myuser
Password: ****

⚠️ Basic認証は認可機能がない
全ユーザーが全リポジトリに push/pull できてしまいます。リポジトリごとのアクセス制御が必要なら Harbor など上位製品（7-5）を検討。

6. ストレージとガベージコレクション

デフォルトでは、イメージはコンテナ内の /var/lib/registry に保存されます。コンテナを rm すると消えるので、Named Volume かホストディレクトリに外出しが必須。

# Named Volume で永続化
docker run -d --name registry \
  -v registry-data:/var/lib/registry \
  -p 5000:5000 \
  registry:2

# または S3 バックエンドを使う（本格運用）
-e REGISTRY_STORAGE=s3 \
-e REGISTRY_STORAGE_S3_BUCKET=my-registry \
-e REGISTRY_STORAGE_S3_REGION=us-east-1 \
...

ガベージコレクション（不要レイヤー削除）

# イメージタグを削除しても、レイヤーファイル自体はディスクに残る
# 定期的にGCを実行してディスクを解放
docker exec registry \
  registry garbage-collect /etc/docker/registry/config.yml

# dry-run で影響範囲を確認
docker exec registry \
  registry garbage-collect --dry-run /etc/docker/registry/config.yml

💡 GC 中は read-only 運用がお勧め
GCと同時に push が走ると、まだ参照される予定のレイヤーを誤って消す可能性があります。公式ドキュメントも「GC 中は readonly モードにせよ」と推奨。

7. Harbor など他選択肢との比較

選択肢	特徴	向く規模
`registry:2`（本記事）	軽量・シンプル・機能最小	個人〜小規模チーム
Harbor	ユーザー管理・脆弱性スキャン・複製同期など全部入り	中〜大規模企業
GitLab Container Registry	GitLab利用なら自動で付いてくる	GitLab利用組織
クラウドマネージド（ECR/GAR/ACR）	運用不要・TLS/認証付き	クラウド運用組織

「とりあえず社内配布したい」なら registry:2、「本格的に管理したい」なら Harbor（詳しくは 7-5）。

8. まとめ

押さえどころ	内容
最速起動	`docker run -d -p 5000:5000 registry:2`
イメージ名	`<registry-host>:5000/<image>:<tag>`
HTTPで使うとき	`insecure-registries` に追加（開発限定）
本番は必ずTLS	証明書指定 or リバースプロキシ前段
認証	Basic（htpasswd）または Harbor で上位RBAC
ストレージ	Named Volume / ホストパス / S3
GC	定期実行・実行中は readonly 推奨