2026'da Homarr'ı Self-Host Etme: Dashboard'lar, Secret'lar ve Canlı Kutucuklar

Bir Homarr container'ı yeşil durumda olabilir, ancak kullanıcıların önem verdiği işlev çalışmıyor olabilir. Homarr'da bu gizli arıza genellikle widget'ların host-local adresler kullandıkları için servislere ulaşamamasıdır. Bu rehberde “bir board oluştur, bir servis kutucuğu ekle, credential gerektiren bir integration yapılandır ve restart sonrasında canlı durumu ve search özelliğini doğrula” akışını kabul testi olarak ele alıyor ve deployment'ı bu sonuçtan geriye doğru tasarlıyoruz.

Homarr'ın stack'teki rolü nettir: self-hosted servisler için search özellikli, canlı kutucuklara sahip bir dashboard. Bu nedenle production sorusu, 7575 portunun bir kez yanıt verip vermediği değil; state'in, dependency'lerin ve public adresin restart, update ve restore sonrasında uyumlu kalıp kalmadığıdır.

Önce Homarr için başarı kriterini tanımlayın

Production mimarisini yanlışlıkla Homarr image'ının belirlemesine izin vermeyin. Image, 7575 üzerinde çalışan bir process sağlar; storage, routing ve external gereksinimlerin lifecycle'ları yine bilinçli şekilde yönetilmelidir. Local runtime gereksinimi, kalıcı app data ve canlı integration'lar için credential'ları içerir. Bunlar, bir sahibi ve ölçülebilir bir limiti olan capacity ve mount planında yer almalıdır.

Deployment; bir board oluşturabildiğinde, bir servis kutucuğu ekleyebildiğinde, credential gerektiren bir integration yapılandırabildiğinde ve restart sonrasında canlı durumu ve search özelliğini doğrulayabildiğinde daha kapsamlı testlere hazırdır. Log'larda transaction'ı takip edin; widget request fan-out'u, downstream API latency'sini, app-data boyutunu ve eş zamanlı dashboard client'larını izleyin. Bu gözlemler, mevcut topology'nin doğru component'i izole edip etmediğini ortaya çıkarır.

Riskli Homarr değişikliğini prova edin

Yeşil durumdaki bir container gereklidir, ancak tek başına yeterli değildir. Service-level indicator, “bir board oluştur, bir servis kutucuğu ekle, credential gerektiren bir integration yapılandır ve restart sonrasında canlı durumu ve search özelliğini doğrula” akışının başarıyla tamamlanmasıdır. Olası baskı sinyalleri ise widget request fan-out'u, downstream API latency'si, app-data boyutu ve eş zamanlı dashboard client'larıdır.

Change control önemlidir; çünkü Homarr schema migration'ları ve encryption key sürekliliği, kayıtlı integration credential'larını etkileyebilir. Eski image'ı saklayın, migration'ları kopyalanmış state üzerinde test edin ve schema değişikliğinden sonra rollback'in desteklenip desteklenmediğini belgeleyin. Widget'lar host-local adresler kullandıkları için servislere ulaşamıyorsa, çalışan environment'tan farklı olan ilk sınırı teşhis edin.

Bilinen ve sorunsuz bir Homarr deployment'ını kaydedin

İlk kullanıcı trafiğini Homarr için kabul testi olarak kullanmayın. Zararsız örnek state hazırlayın ve “bir board oluştur, bir servis kutucuğu ekle, credential gerektiren bir integration yapılandır ve restart sonrasında canlı durumu ve search özelliğini doğrula” işleminin tamamını çalıştırın. Çalıştırmayla ilişkili tam public URL'yi, sonucu, image referansını ve log aralığını not edin.

Container'ı değiştirin ve data'yı yeniden oluşturmadan işlemi tekrarlayın. Ardından boş bir host üzerinde recovery yapın; recovery koşulu, board'ların, user'ların, integration'ların ve custom asset'lerin geri gelmesi ve credential kullanan widget'ların yeniden bağlanmasıdır. Her geçişte widget request fan-out'unu, downstream API latency'sini, app-data boyutunu ve eş zamanlı dashboard client'larını gözlemleyin; idle container metric'leri yerine transaction'ın kötüleşmesi etrafında bir alert tanımlayın.

Son bir kontrol bilerek başarısız olmalıdır: bu sınırla ilişkili resource veya format limitine yakın, zararsız bir input gönderin: widget'lar host-local adresler kullandıkları için servislere ulaşamıyor. Ortaya çıkan Homarr mesajının, data silmeyi veya sonsuz bir restart döngüsünü tetiklemek yerine ilgili sınırı tanımladığını doğrulayın. Geçerli koşulu geri yükleyin ve aynı örnek transaction'ın başarıyla tamamlandığını doğrulayın. Bu kısa tatbikatı release checklist'inde tutun.

İlk production benzeri instance'ı çalıştırın

İlk container'ın silinmesi ve yeniden oluşturulması kolay olmalıdır. Data'yı writable layer'dan uzak tutun, 7575 portunu yalnızca proxy'nin erişebileceği yerde bind edin ve configuration'ı runtime'da geçin.

docker run -d \
  --name homarr \
  --restart unless-stopped \
  -p 127.0.0.1:7575:7575 \
  -v homarr-data:/appdata \
  -e SECRET_ENCRYPTION_KEY=replace-with-a-long-random-value \
  ghcr.io/homarr-labs/homarr:latest

İlk testten sonra image'ı pinleyin. Son restart mesajı yerine en erken startup error'ını okuyun, her mount'ı docker inspect ile doğrulayın ve bir board oluşturup bir servis kutucuğu eklerken, credential gerektiren bir integration yapılandırırken ve restart sonrasında canlı durumu ve search özelliğini doğrularken log'ları takip edin. Bu sıra; hatalı bir image komutunu dependency veya permission probleminden ayırır.

Volume'lar recovery'nin yalnızca ilk katmanıdır

Homarr için redeploy güvenliği board'larla, user'larla, integration'larla, secret'larla ve custom asset'lerle başlar. Bootstrap işleminden önce /appdata'yı mount edin, zararsız örnek data yazın ve bu path'in gerçekten kalıcı olduğunu kanıtlamak için container'ı değiştirin. Zararsız örnek data mevcutken container'ı değiştirerek path'i test edin; bu yöntem, mount'ların bir üst veya bir alt directory'ye yönlendirilmiş olduğunu ortaya çıkarır.

Ardından boş bir host üzerinde disaster recovery'yi test edin. Gerektiğinde application-consistent bir database export kullanın ve board'ların, user'ların, integration'ların ve custom asset'lerin geri geldiğini, credential kullanan widget'ların yeniden bağlandığını doğrulayın. Restore edilmiş database backup rehberi, yalnızca bir archive file oluşturulduğunu kontrol etmekten daha güçlü bir hedef sunar.

Proxy başarısının application arızasını gizlemesini önleyin

Browser, API client ve Homarr tek bir origin üzerinde anlaşmalıdır. Bunu sağlamak için external HTTPS hostname'i ve allowed origins'i ayarlayın. Original host ve protocol'ü korurken 7575 portunun rakip bir public adres olarak erişilebilir olmasını engelleyin.

Site down troubleshooting rehberi, erişilemeyen bir route ile yanıt veren bir application'ı ayırt etmenize yardımcı olur. Bu ayrım burada önemlidir: widget'lar host-local adresler kullandıkları için servislere ulaşamıyor. İlk sorun ingress değişiklikleriyle çözülür; ikincisi ise Homarr log'larının, state'inin veya workload'un incelenmesini gerektirir.

Geçici setup erişimini kapatın

Güvenli bir Homarr deployment'ı authority'yi azaltarak başlar. Integration secret'ları saklandıktan sonra encryption key'i değiştirmekten kaçının; bunun yerine SECRET_ENCRYPTION_KEY'i sabit tutun, board düzenleme yetkisini koruyun ve her widget credential'ının kapsamını sınırlandırın.

SECRET_ENCRYPTION_KEY'i bir kez oluşturun, Git dışında tutun ve recovery manifest'iyle birlikte saklayın; çünkü bu değerin değiştirilmesi, encrypted veya signed application state'ini geçersiz kılabilir. Administrative route'ları kısıtlayın, dependency'ler için private DNS kullanın ve her bind mount'ı gözden geçirin. Log'lar merkezi olarak gönderildiğinde, server'dan çıkmadan önce secret'ları ve private content'i filtreleyin.

Tekrarlanabilir infrastructure işlerini Dockup'a taşıyın

Homarr için Dockup en çok image ile kalıcı bir service arasındaki sınırda fayda sağlar. Compute Dockup'a veya bağladığınız server'a ait olsa da, 7575'e giden route'u, TLS'i, secret değerlerini ve storage'ı container değişiklikleri boyunca bağlı tutar.

Son olarak application bilgisini ekleyin: external HTTPS hostname'i ve allowed origins'i ayarlayın; local gereksinimi — canlı integration'lar için kalıcı app data ve credential'lar — doğrulayın; ardından şu doğrulamayı çalıştırın: bir board oluşturun, bir servis kutucuğu ekleyin, credential gerektiren bir integration yapılandırın ve restart sonrasında canlı durumu ve search özelliğini doğrulayın. Sonucu deployment check olarak saklayın; böylece bir sonraki image update'i container status'a göre değil, davranışa göre değerlendirilir.

Sık sorulan sorular

Production deployment için Homarr'ın neye ihtiyacı var?

Homarr container'ını tek bir HTTPS origin üzerinden 7575 portunda route edin. Local runtime gereksinimi, canlı integration'lar için kalıcı app data ve credential'ları içerir. Bir board oluşturabildiğiniz, bir servis kutucuğu ekleyebildiğiniz, credential gerektiren bir integration yapılandırabildiğiniz ve restart sonrasında canlı durumu ve search özelliğini doğrulayabildiğiniz ana kadar Homarr'ı hazır kabul etmeyin.

Hangi Homarr verileri backup'a dahil edilmelidir?

/appdata'yı persist edin ve board'ları, user'ları, integration'ları, secret'ları ve custom asset'leri aynı recovery manifest'ine dahil edin. Başarılı bir Homarr restore işlemi, yalnızca board'lar, user'lar, integration'lar ve custom asset'ler geri geldiğinde ve credential kullanan widget'lar yeniden bağlandığında tamamlanmış sayılır.

Reverse proxy arkasında Homarr için HTTPS gerekli mi?

Public Homarr origin'i için HTTPS kullanın ve 7575 portunu internal route üzerinde tutun. Homarr ayarını doğru uygulayın: external HTTPS hostname'i ve allowed origins'i ayarlayın. Homarr için HTTPS, credential'ları veya user content'ini transit sırasında korur ve origin'e duyarlı client davranışının tutarlı kalmasını sağlar.

Homarr upgrade'i nasıl test edilmelidir?

Mevcut Homarr state'ini izole bir deployment'a restore edin, aday version'ı uygulayın ve kabul transaction'ını tekrarlayın. Homarr schema migration'ları ve encryption key sürekliliği, kayıtlı integration credential'larını etkileyebileceğinden bu noktaya özellikle dikkat edin. Data migration ve rollback sınırları anlaşılana kadar önceki Homarr image'ını saklayın.