Cara Membuat Docker Registry Pribadi di VPS

Pernah kesal karena image aplikasi kantor harus diunggah ke registry publik, padahal isinya kode internal? Atau proses deploy jadi lambat karena setiap server menarik image dari luar negeri? Jawabannya bisa sesederhana menjalankan registry sendiri di satu VPS.

Registry pribadi adalah tempat menyimpan image Docker yang hanya bisa diakses timmu. Proyek resminya bernama Distribution (dulu Docker Registry), dan image siap pakainya tersedia di Docker Hub dengan nama registry. Versi 3 memakai tag registry:3.

Apa yang perlu disiapkan dulu?

Sebelum mulai, pastikan beberapa hal ini sudah ada:

• VPS Linux dengan Docker Engine dan plugin Compose terpasang. Kalau belum akrab dengan Docker, baca dulu apa itu Docker.
• Subdomain khusus, misalnya registry.contoh.co.id, yang record A-nya mengarah ke IP VPS.
• Ruang disk yang cukup. Image menumpuk lebih cepat dari dugaan, terutama kalau setiap commit menghasilkan tag baru.
• Port 80 dan 443 terbuka untuk reverse proxy. Port registry sendiri (5000) cukup didengarkan di localhost.

Langkah membuat registry pribadi

Langkah 1: Buat folder kerja dan file login

Registry hanya menerima file htpasswd berformat bcrypt, jadi opsi -B wajib dipakai. Cara termudah membuatnya adalah meminjam program htpasswd dari image httpd:2, seperti contoh di dokumentasi resmi:

mkdir -p /opt/registry/{auth,data}
cd /opt/registry
docker run --rm --entrypoint htpasswd httpd:2 -Bbn timdev PasswordPanjangSekali > auth/htpasswd

Ganti timdev dan kata sandinya. Untuk menambah pengguna lain, jalankan perintah yang sama dengan >> agar file tidak tertimpa.

Langkah 2: Tulis docker-compose.yml

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

Perhatikan 127.0.0.1:5000:5000. Dengan cara ini registry tidak langsung terbuka ke internet, hanya bisa dijangkau reverse proxy di server yang sama. Ini penting karena Docker suka menembus aturan firewall, seperti dibahas di cara mengamankan Docker di VPS agar port tidak bocor.

Variabel REGISTRY_STORAGE_DELETE_ENABLED mengizinkan penghapusan image lewat API. Tanpa ini, langkah pembersihan di bawah tidak banyak berguna.

Jalankan dengan docker compose up -d, lalu cek docker compose logs -f registry.

Langkah 3: Pasang HTTPS lewat reverse proxy

Klien Docker menolak registry tanpa TLS kecuali alamatnya localhost atau kamu menandainya sebagai insecure-registries di setiap mesin. Pilihan kedua merepotkan dan tidak aman, jadi pakai sertifikat sungguhan.

Registry sebenarnya bisa memegang sertifikat sendiri lewat REGISTRY_HTTP_TLS_CERTIFICATE dan REGISTRY_HTTP_TLS_KEY. Namun di VPS yang juga melayani situs lain, reverse proxy lebih praktis. Contoh potongan server block Nginx:

server {
    listen 443 ssl;
    server_name registry.contoh.co.id;
    # baris ssl_certificate dari Certbot

    client_max_body_size 0;
    chunked_transfer_encoding on;

    location /v2/ {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 900;
    }
}

client_max_body_size 0 mematikan batas ukuran unggahan. Tanpa baris ini, push layer besar akan gagal dengan error 413.

Langkah 4: Login, tag, dan push

Dari laptop atau server CI:

docker login registry.contoh.co.id
docker tag aplikasi:1.4.0 registry.contoh.co.id/tim/aplikasi:1.4.0
docker push registry.contoh.co.id/tim/aplikasi:1.4.0

Di server produksi, cukup docker login sekali lalu docker pull seperti biasa. Untuk melihat isi registry, panggil API katalog:

curl -u timdev https://registry.contoh.co.id/v2/_catalog

Bagaimana membersihkan image lama secara berkala?

Menghapus tag lewat API tidak langsung mengosongkan disk. Data layer baru benar-benar hilang setelah garbage collection. Dokumentasi resmi meminta registry dalam keadaan berhenti atau read-only selama proses ini, karena push yang berjalan bersamaan bisa merusak data.

Mulai versi 3, lokasi konfigurasi bawaan pindah ke /etc/distribution/config.yml. Jalankan dulu dalam mode uji:

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

Opsi --delete-untagged ikut membuang manifest yang tidak lagi punya tag. Jadwalkan ini di jam sepi, misalnya seminggu sekali.

Registry sendiri atau layanan terkelola?

Registry bawaan ini cocok untuk tim kecil sampai menengah dengan satu atau dua kelompok pengguna. Kalau butuh hak akses per proyek, antarmuka web, atau pemindaian celah otomatis, lihat solusi yang lebih lengkap seperti Harbor. Sementara itu, image di registry sendiri tetap bisa kamu periksa dengan Trivy sebelum dipakai di produksi.

Checklist sebelum dipakai tim

• Registry hanya mendengarkan di 127.0.0.1, bukan di semua antarmuka.
• HTTPS aktif dan docker login berhasil dari mesin lain.
• Setiap anggota tim punya akun htpasswd sendiri.
• Jadwal garbage-collect mingguan sudah dibuat dan diuji dengan --dry-run.
• Pemantauan ruang disk aktif agar folder data tidak memenuhi server.