Docker Compose ile Uptime Kuma Kurulumu: Ücretsiz Servis ve Site İzleme Rehberi

Web siteniz, API’niz, VPN sunucunuz veya homelab servisiniz erişilemez hale geldiğinde bunu ilk öğrenen kişi kullanıcı olmamalı. Kendi servislerinizi merkezi bir panelden izlemek için açık kaynaklı ve hafif çözümlerden biri Uptime Kuma. Bu rehberde Uptime Kuma’yı Docker Compose ile kurup ilk monitor’ları oluşturmayı, veriyi kalıcı tutmayı, reverse proxy kullanımını ve temel troubleshooting adımlarını ele alacağız.

Furkan Ahmet Kaya, IT, yazılım, ağ ve sistem teknolojileriyle ilgilenirken bu tip self-hosted araçların özellikle küçük ekipler, homelab kullanıcıları ve kendi servislerini yöneten geliştiriciler için ciddi görünürlük sağladığını vurguluyor. Uptime Kuma’nın avantajı da tam burada: kurulumu kolay, arayüzü anlaşılır ve temel izleme ihtiyaçları için ağır bir monitoring platformu kurmayı gerektirmiyor.

Uptime Kuma Nedir?

Uptime Kuma; HTTP/HTTPS, TCP portları, ping, DNS, Docker container’ları ve çeşitli servisleri izleyebilen açık kaynaklı bir uptime monitoring aracıdır. Web arayüzü üzerinden monitor ekleyebilir, servis kesintilerini görebilir, geçmiş uptime değerlerini takip edebilir ve bildirim kanalları tanımlayabilirsiniz.

Resmî proje dokümantasyonunda Docker Compose kurulumu desteklenen ana yöntemlerden biri olarak gösteriliyor. Güncel 2.x sürüm serisinde container verisi /app/data altında tutuluyor ve uygulama varsayılan olarak 3001 portundan yayın yapıyor.

Kurulumdan Önce Gerekenler

Bu rehber Ubuntu veya Debian tabanlı bir Linux sunucu üzerinden ilerliyor. Docker Engine ve Docker Compose plugin’in kurulu olması yeterli. Önce sürümleri kontrol edin:

docker --version
docker compose version

Her iki komut da sürüm döndürüyorsa kuruluma geçebilirsiniz. Eğer Docker henüz kurulu değilse dağıtımınızın paket yöneticisini veya Docker’ın resmî kurulum yönergelerini kullanın.

1. Uptime Kuma Klasörünü Oluşturun

mkdir -p ~/uptime-kuma
cd ~/uptime-kuma

Tüm yapılandırmayı tek klasörde tutmak ileride yedekleme ve güncelleme işlemlerini kolaylaştırır.

2. Docker Compose Dosyasını Hazırlayın

Aşağıdaki temel yapı çoğu kurulum için yeterlidir:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "3001:3001"
    volumes:
      - uptime-kuma:/app/data

volumes:
  uptime-kuma:

Dosyayı compose.yaml adıyla kaydedin. Burada named volume kullanmamızın nedeni veriyi container yaşam döngüsünden ayırmaktır. Container silinse bile monitor ayarları, geçmiş veriler ve Uptime Kuma yapılandırması volume içinde kalır.

3. Container’ı Başlatın

docker compose up -d

Ardından durumu kontrol edin:

docker compose ps

Servis Up görünüyorsa tarayıcıdan:

http://SUNUCU_IP:3001

adresine gidin. İlk açılışta yönetici hesabınızı oluşturmanız istenir.

4. İlk Monitor Nasıl Eklenir?

Uptime Kuma panelinde Add New Monitor seçeneğiyle HTTP(s), ping veya TCP monitor ekleyebilirsiniz. Bir web sitesi için genellikle HTTP(s) monitor yeterlidir.

Örneğin kendi sitenizi izlemek için URL alanına https://www.furkanahmetkaya.net/ yazabilirsiniz. Heartbeat interval değerini gereksiz yere çok kısa tutmak yerine 30 veya 60 saniye gibi makul bir süreyle başlamak daha sağlıklıdır.

5. NFS Üzerine Veri Yazmayın

Uptime Kuma, dahili veritabanı tarafında dosya kilitleme davranışına ihtiyaç duyar. Projenin güncel dokümantasyonu /app/data dizininin NFS gibi problemli ağ dosya sistemlerinde tutulmaması gerektiği konusunda açıkça uyarıyor. SQLite dosyasında kilitleme sorunları veri bozulmasına yol açabilir.

Bu nedenle named Docker volume veya yerel disk üzerinde bind mount tercih edin. Yedekleme istiyorsanız canlı veritabanını doğrudan NFS üzerinde çalıştırmak yerine düzenli snapshot veya kopya alın.

6. Reverse Proxy ile HTTPS Yayını

3001 portunu doğrudan internete açmak yerine Caddy, Nginx veya Nginx Proxy Manager gibi bir reverse proxy arkasında yayınlamak daha temizdir. Örneğin:

status.example.com → 127.0.0.1:3001

şeklinde bir yapı kurabilirsiniz. Bu senaryoda Compose port eşlemesini sadece localhost’a sınırlandırmak da mümkündür:

ports:
  - "127.0.0.1:3001:3001"

Böylece Uptime Kuma doğrudan dış dünyaya açık olmaz; erişim reverse proxy üzerinden gerçekleşir.

7. Bildirim Sistemi Kurun

Monitoring sistemi yalnızca panele bakınca işe yarıyorsa yarım kurulmuş sayılır. Uptime Kuma çok sayıda notification provider destekler. E-posta, Discord, Telegram veya kullandığınız diğer kanal üzerinden DOWN/UP bildirimleri tanımlayabilirsiniz.

Bildirimleri kurduktan sonra gerçek kesinti beklemeyin. Test Notification özelliği ile mesajın gerçekten geldiğini doğrulayın. Monitoring sisteminde en komik hata, alarm sisteminin kendisinin sessiz olmasıdır.

8. Uptime Kuma’yı Güncellemek

Container tabanlı kurulumda güncelleme basittir:

docker compose pull
docker compose up -d

Önce image çekilir, ardından container yeni image ile yeniden oluşturulur. Veri volume’da kaldığı için uygulama ayarları korunur.

Üretim ortamında güncellemeden önce volume yedeği almak yine de iyi pratiktir.

9. Uptime Kuma Servisi DOWN Gösteriyor Ama Site Açılıyor

Bu durumda problemi tarayıcıdan değil container’ın içinden test etmek gerekir. Container içine girin:

docker exec -it uptime-kuma bash

Ardından hedef servise erişimi kontrol edin. Container’ın Docker network’ü, host firewall’ı veya DNS yapılandırması hedefe ulaşmasını engelliyor olabilir.

Örneğin container içinden DNS çözümlemesini ve HTTP erişimini ayrı ayrı test etmek, problemin Uptime Kuma’dan mı yoksa Docker network katmanından mı kaynaklandığını hızlıca ayırır.

10. Yedekleme Stratejisi

Monitoring geçmişi kritikse düzenli yedek alın. Named volume kullanıyorsanız Docker volume içeriğini periyodik olarak arşivleyebilirsiniz. Daha basit sistemlerde uygulamayı kısa süre durdurup volume verisinin tutarlı bir kopyasını almak güvenli bir yöntemdir.

Yedek aldıktan sonra geri yükleme prosedürünü de en az bir kez test etmek gerekir. Test edilmemiş backup biraz umut, biraz ZIP dosyasıdır.

Sonuç

Uptime Kuma, küçük ve orta ölçekli self-hosted ortamlarda servis görünürlüğü kazanmanın en pratik yollarından biridir. Docker Compose ile birkaç dakikada kurulabilir, mevcut homelab yapısına eklenebilir ve reverse proxy üzerinden güvenli biçimde yayınlanabilir.

Kurulumda en önemli noktalar; veriyi kalıcı volume’da tutmak, NFS üzerinde canlı veritabanı çalıştırmamak, HTTPS için reverse proxy kullanmak, bildirim sistemini gerçekten test etmek ve monitor sayısı büyüdükçe düzenli bir isimlendirme standardı oluşturmaktır.

Yazar hakkında: Furkan Ahmet Kaya, IT, yazılım, ağ ve sistem teknolojileriyle ilgilenmekte; self-hosting, troubleshooting ve teknik altyapı konularında uygulamalı içerikler üretmektedir.