2026'da Verdaccio'yu Self-Host Etme: npm Auth, Storage ve TLS

Verdaccio'yu self-host etmek, ilk docker run komutunda değil, ilk redeploy işleminde önem kazanmaya başlar. npm client'ları auth bilgilerini farklı bir host'a gönderiyorsa veya package storage salt okunursa Docker yine tamamen sağlıklı görünen bir process bildirebilir. Aşağıdaki deployment, gözlemlenebilir davranışlar etrafında düzenlenmiştir: npm ile giriş yapın, scoped bir package publish edin, bunu temiz bir project'ten install edin ve bir upstream package'ın cache'lendiğini doğrulayın.

Verdaccio'nun hedeflenen kullanım amacı nettir: internal package'ler için private npm registry. Bu tanım, nelerin public kalması, nelerin private tutulması ve bir backup'ın neleri yeniden oluşturması gerektiğini açıkça ortaya koyar.

Portlar, process'ler ve private service'ler

Kullanışlı bir Verdaccio diyagramı public route'u, private 4873 portunu, state sınırını ve tüm supporting requirement'ları gösterir. Hangi okların credential taşıdığını, hangilerinin ise sıradan user trafiği olduğunu işaretleyin. Verdaccio'nun network contract'ı persistent configuration, htpasswd storage ve optional object storage'dan oluşur. Private endpoint'leri internal DNS üzerinde tutun, yalnızca gerekli outbound çağrılara izin verin ve Verdaccio'ya kapsamı sınırlandırılmış bir service credential sağlayın.

Diyagramı tek bir gerçek işlemle doğrulayın: npm ile giriş yapın, scoped bir package publish edin, bunu temiz bir project'ten install edin ve bir upstream package'ın cache'lendiğini doğrulayın. Muhtemel yük tarball storage, metadata operasyonları, eş zamanlı install işlemleri ve yapılandırılmış upstream registry'lere olan latency'den kaynaklanır; tüm HTTP request'lerini eşit kabul etmek yerine bu path'i izleyin.

Local command'ı inspect edilebilir bir service'e dönüştürme

Her önemli seçeneği görünür kılan bir command kullanın. Bu baseline, Verdaccio'yu host loopback'e bind eder, bilinen data mount'larını ekler ve gerekli ilk setting'i sağlar. Persistent configuration, htpasswd storage ve optional object storage için gözden geçirilmiş connection setting'lerini ekleyin; private service'ler için private isimler kullanın.

docker run -d \
  --name verdaccio \
  --restart unless-stopped \
  -p 127.0.0.1:4873:4873 \
  -v verdaccio-data:/verdaccio/storage \
  -e VERDACCIO_PUBLIC_URL=https://app.example.com \
  verdaccio/verdaccio:latest

Değişken tag'leri, test edilmiş bir version veya digest ile değiştirin. Başlangıçtan sonra docker logs --tail 200 verdaccio çıktısını inceleyin ve process'in 4873 portunu dinlediğini doğrulayın. Ardından Verdaccio acceptance action'ını çalıştırın; root page response'u, senaryonun tamamının başarılı olduğunu kanıtlayamaz: npm ile giriş yapın, scoped bir package publish edin, bunu temiz bir project'ten install edin ve bir upstream package'ın cache'lendiğini doğrulayın.

TLS kolaydır; oluşturulan URL'ler değildir

Public URL ile npm registry URL'sini aynı HTTPS origin'ine ayarlayın. Seçilen hostname'i container'ın 4873 portuna yönlendirin, original host'u ve HTTPS scheme'ini forward edin ve ikinci bir direct origin yayınlamaktan kaçının.

Verdaccio'yu temiz bir external client'tan test edin. Ingress hatasını bilinen application boundary'den ayırın — npm client'ları auth bilgilerini farklı bir host'a gönderiyor olabilir veya package storage salt okunur olabilir. Certificate, DNS veya 502 hatası routing kapsamındadır; Verdaccio'ya ulaşan ve daha sonra başarısız olan bir request ise application state'i, capacity veya supporting requirement'ları işaret eder. custom-domain TLS guide ilk grubu kapsar.

Verdaccio'yu boş bir host üzerinde restore etme

Verdaccio için redeploy güvenliği package tarball'ları, metadata'yı, config'i ve authentication file'larını kapsamakla başlar. Bootstrap işleminden önce /verdaccio/storage'ı mount edin, zararsız sample data yazın ve bu path'in gerçekten persistent olduğunu kanıtlamak için container'ı değiştirin. Zararsız sample data mevcutken container'ı değiştirerek path'i test edin; bu işlem, mount'ların bir directory fazla yukarıya veya aşağıya işaret etmesini ortaya çıkarır.

Sonraki adımda disaster recovery'yi boş bir host üzerinde test edin. Gerektiğinde application-consistent database export kullanın ve private tarball'ların, metadata'nın, user'ların ve config'in geri geldiğini; temiz project'in aynı package integrity ile install yaptığını doğrulayın. restore-tested database backup guide, yalnızca bir archive file oluşturulduğunu kontrol etmekten daha güçlü bir hedef sunar.

Credential'lar, role'ler ve exposed surface'ler

Verdaccio için değerli surface mutlaka landing page değildir. En büyük hata anonymous publish'e izin vermek veya writable bir uplink configuration kullanmaktır. Buna bilinçli şekilde karşı koyun: anonymous publish'i engelleyin, maintainer'ların kapsamını sınırlandırın ve npm authentication'ı tam olarak HTTPS registry host'una bağlayın.

VERDACCIO_PUBLIC_URL bir secret değil, configuration'dır; değerini açıkça belirtirken Verdaccio'nun kullandığı ayrı credential'ları koruyun. Image destekliyorsa unprivileged container user kullanın ve ilgisiz credential'ları mount etmeyin. Güvenilmeyen işlemlerin tarball storage'ı, metadata operasyonlarını, eş zamanlı install'ları ve yapılandırılmış upstream registry'lere olan latency'yi tüketebileceği ingress katmanında rate veya size limit'leri uygulayın.

Verdaccio için failure drill'leri

Capacity test'leri / adresine tekrarlanan bir request göndermek yerine tarball storage'ı, metadata operasyonlarını, eş zamanlı install'ları ve yapılandırılmış upstream registry'lere olan latency'yi çalıştırmalıdır. “npm ile giriş yap, scoped bir package publish et, bunu temiz bir project'ten install et ve bir upstream package'ın cache'lendiğini doğrula” senaryosunu gerçekçi concurrency ile çalıştırın; latency'yi, error rate'i ve storage büyümesini kaydedin.

Upgrade planlaması şu riski hesaba katmalıdır: config syntax'ı, authentication plugin'leri ve package metadata'sı hedef Verdaccio major version'ına karşı test edilmelidir. Yeni release'i temsili input'larla test edin, ardından acceptance transaction'ı tekrarlayın ve sonucu karşılaştırın. npm client'ları auth bilgilerini farklı bir host'a gönderiyorsa veya package storage salt okunuyorsa başarısız transaction'ı kaydedin ve ingress'in sorumlu olduğunu varsaymak yerine ilgili ilk boundary'yi inceleyin.

Verdaccio deployment'ını uçtan uca doğrulama

Verdaccio için ilk user trafiğini acceptance test'i olarak kullanmayın. Zararsız sample state hazırlayın ve “npm ile giriş yap, scoped bir package publish et, bunu temiz bir project'ten install et ve bir upstream package'ın cache'lendiğini doğrula” işleminin tamamını çalıştırın. Çalıştırmayla ilişkili tam public URL'yi, sonucu, image reference'ını ve log interval'ini not edin.

Data'yı yeniden oluşturmadan container'ı değiştirin ve işlemi tekrarlayın. Ardından boş bir host'a recovery yapın; recovery koşulu, private tarball'ların, metadata'nın, user'ların ve config'in geri gelmesi ve temiz project'in aynı package integrity ile install yapmasıdır. Her geçişte tarball storage'ı, metadata operasyonlarını, eş zamanlı install'ları ve yapılandırılmış upstream registry'lere olan latency'yi gözlemleyin ve idle container metric'leri yerine transaction'daki degradation etrafında bir alert tanımlayın.

Son bir kontrol kasıtlı olarak başarısız olmalıdır: test identity'sinin persistent configuration, htpasswd storage ve optional object storage'a erişimini geçici olarak engelleyin. Ortaya çıkan Verdaccio mesajının, data silmeyi veya sonsuz bir restart döngüsünü tetiklemek yerine ilgili boundary'yi belirlediğini doğrulayın. Geçerli koşulu geri yükleyin ve aynı sample transaction'ın başarılı olduğunu doğrulayın. Bu kısa drill'i release checklist'inde tutun.

Verdaccio'yu açıkça tanımlarken routing'i Dockup'a bırakma

Verdaccio için Dockup route'u ve TLS certificate'ını oluşturabilir, mount'ları koruyabilir, secret'ları sağlayabilir ve persistent configuration, htpasswd storage ile optional object storage'ı private networking üzerine yerleştirirken deployment'ı Dockup'a veya bağlı server'lara yapabilir.

Release gate yine somut Verdaccio transaction'ıdır: npm ile giriş yapın, scoped bir package publish edin, bunu temiz bir project'ten install edin ve bir upstream package'ın cache'lendiğini doğrulayın. Ayrıca recovery koşulunu da doğrulayın — private tarball'lar, metadata, user'lar ve config geri gelmeli; temiz project aynı package integrity ile install yapmalıdır. Bu iki kontrol, deployment'ın çalışıp çalışmadığını ve kurtarılıp kurtarılamayacağını gösterir.

Sık sorulan sorular

Production deployment için Verdaccio'nun neye ihtiyacı vardır?

Verdaccio container'ını tek bir HTTPS origin üzerinden 4873 portuna route edin. Supporting network requirement; persistent configuration, htpasswd storage ve optional object storage'dır. npm ile giriş yapamıyor, scoped bir package publish edemiyor, bunu temiz bir project'ten install edemiyor ve bir upstream package'ın cache'lendiğini doğrulayamıyorsanız Verdaccio'yu hazır kabul etmeyin.

Hangi Verdaccio verileri backup'a dahil edilmelidir?

/verdaccio/storage'ı persistent hale getirin ve package tarball'larını, metadata'yı, config'i ve authentication file'larını aynı recovery manifest'ine dahil edin. Temiz bir Verdaccio restore'u yalnızca private tarball'lar, metadata, user'lar ve config geri geldiğinde ve temiz project aynı package integrity ile install yaptığında başarılı sayılır.

Reverse proxy arkasında Verdaccio için HTTPS gerekir mi?

Public Verdaccio origin'i için HTTPS kullanın ve 4873 portunu internal route üzerinde tutun. Verdaccio setting'ini doğru uygulayın: public URL ile npm registry URL'sini aynı HTTPS origin'ine ayarlayın. Verdaccio için HTTPS, credential'ları veya user content'ini aktarım sırasında korur ve origin'e duyarlı client davranışını tutarlı hale getirir.

Verdaccio upgrade'i nasıl test edilmelidir?

Mevcut Verdaccio state'ini izole bir deployment'a restore edin, candidate version'ı uygulayın ve acceptance transaction'ını tekrarlayın. Özellikle dikkatli olun; config syntax'ı, authentication plugin'leri ve package metadata'sı hedef Verdaccio major version'ına karşı test edilmelidir. Data migration ve rollback boundary'leri anlaşılana kadar önceki Verdaccio image'ını saklayın.