Uptime Kuma 2, Docker Compose ve HTTPS ile nasıl kurulur

Uptime Kuma, sade bir web arayüzüne sahip self-hosted bir izleme aracıdır. Web sitelerini, API'leri, TCP portlarını, DNS kayıtlarını, ping hedeflerini ve daha fazlasını belirli aralıklarla kontrol eder, bir şey çöktüğünde onlarca bildirim servisi üzerinden uyarı gönderir ve kullanıcılarınız için herkese açık durum sayfaları yayınlayabilir. 2. sürüm güncel ana sürümdür.

Bu rehber Uptime Kuma 2'yi projenin resmi Docker Compose dosyasıyla kurar, web arayüzünü yalnızca 127.0.0.1 üzerinde yayınlar ve arayüzün ihtiyaç duyduğu WebSocket bağlantısını da ileten Caddy ile HTTPS üzerinden sunar. Ardından bir veritabanı seçer, iki faktörlü doğrulamalı yönetici hesabını oluşturur, ilk izleyicilerinizi, bildirimlerinizi ve bir durum sayfasını ekler; kurulumu nasıl yedekleyeceğinizi, güncelleyeceğinizi ve sorunlarını nasıl gidereceğinizi öğrenirsiniz.

Adım 1 — Resmi Compose dosyasını alın

Uygulama klasörünü oluşturun ve projenin README dosyasında önerilen Compose dosyasını indirin:

sudo mkdir -p /opt/uptime-kuma
sudo chown $USER:$USER /opt/uptime-kuma
cd /opt/uptime-kuma
curl -fsSL -o compose.yaml https://raw.githubusercontent.com/louislam/uptime-kuma/master/compose.yaml
cat compose.yaml

Dosya louislam/uptime-kuma:2 imajını çalıştırır, tüm verileri ./data klasöründe (/app/data olarak bağlanır) tutar ve 3001 numaralı portu sunucunun tüm adreslerinde yayınlar. Docker'ın yayınladığı portlar ufw'yi atladığı için port satırını yalnızca loopback adresinde dinleyecek şekilde değiştirin. Dosyayı nano compose.yaml ile açın ve şu hale getirin:

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

İmaj etiketi hakkında: 2 en yeni 2.x sürümünü izler ve projenin önerdiği etikettir. 2.5.5 gibi tam etiketler bir sürüme sabitler, 2-slim daha küçük türevdir, latest ise kullanımdan kalkmıştır ve hâlâ 1. sürümü gösterir.

Adım 2 — Uptime Kuma'yı başlatın

docker compose up -d
docker compose ps
docker compose logs --tail 30
curl -I http://127.0.0.1:3001

docker compose ps konteyneri çalışıyor olarak gösterir, loglarda hata görünmez ve curl bir HTTP durum satırıyla yanıt verir (bu aşamada kurulum sayfasına yönlendirme normaldir). Arayüz henüz internetten erişilebilir değildir; bu bilinçli bir tercihtir.

Adım 3 — Uptime Kuma'yı Caddy ile HTTPS üzerinden sunun

/etc/caddy/Caddyfile dosyasına bir site bloğu ekleyin. Caddy'nin reverse_proxy yönergesi WebSocket bağlantılarını kendiliğinden yükselttiği için ek başlık gerekmez:

status.example.com {
    reverse_proxy 127.0.0.1:3001
}

Caddy'yi yeniden yükleyin ve güvenlik duvarında yalnızca SSH ile web trafiğine izin verin:

sudo systemctl reload caddy
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
curl -I https://status.example.com

Son komut geçerli bir sertifika üzerinden yanıt döndürür. Bunun yerine Nginx kullanıyorsanız (Nginx ve Certbot), projenin reverse proxy wiki sayfasında gösterildiği gibi WebSocket için Upgrade ve Connection başlıklarını ekleyin; Traefik WebSocket'i kendisi yönetir.

Adım 4 — Veritabanını seçin ve yönetici hesabını oluşturun

https://status.example.com adresini hemen açın; kurulumu bitirene kadar adresi bulan herkes yönetici hesabını sahiplenebilir.

1. İlk ekran hangi veritabanının kullanılacağını sorar. SQLite küçük ölçekli kurulumlar için önerilen basit bir veritabanı dosyası olarak tanımlanır ve çoğu tek sunuculu kurulum için doğru seçimdir. Embedded MariaDB aynı konteynerin içinde bir MariaDB sunucusu çalıştırır (yalnızca tam imajda). MariaDB/MySQL harici bir veritabanı sunucusuna bağlanır.
2. Benzersiz bir kullanıcı adı ve parola yöneticinizden alınmış uzun bir parolayla yönetici hesabını oluşturun.

Boş kontrol paneline ulaşırsınız. Ardından hesabı güçlendirin:

• Settings, ardından Security bölümünü açın ve Two Factor Authentication altında Set Up 2FA seçeneğini kullanın. QR kodunu bir doğrulayıcı uygulamayla tarayın ve bir kodla onaylayın.
• Settings, ardından Reverse Proxy bölümünü açın ve HTTP Headers altında Trust Proxy değerini Yes yapın. Uptime Kuma böylece 127.0.0.1 yerine Caddy'nin gönderdiği gerçek ziyaretçi IP adreslerini loglar. Bunu yalnızca uygulamaya, buradaki gibi, sadece proxy'niz üzerinden erişilebiliyorsa yapın.

Adım 5 — İzleyiciler, bildirimler ve bir durum sayfası ekleyin

Önce bildirimler. Settings, ardından Notifications bölümünü açın ve Setup Notification düğmesine tıklayın. Bir servis seçin (SMTP ile e-posta, Telegram, Discord, Slack, Microsoft Teams, ntfy, webhook ve daha birçoğu), bilgilerini doldurun ve kaydetmeden önce Test düğmesini kullanın. Yeni izleyicilere kendiliğinden eklenmesi için Default enabled seçeneğini işaretleyin. E-posta uyarıları için relay sunucunuzun adını (örneğin smtp.example.com), STARTTLS güvenliğiyle 587 portunu, SMTP kullanıcı adınızı ve parolanızı, gönderen ve alıcı adreslerini girin.

Sonra izleyiciler. Add New Monitor düğmesine tıklayın ve bir tür seçin:

• HTTP(s) bir adresin başarılı bir durum koduyla yanıt verdiğini kontrol eder; HTTP(s) - Keyword ayrıca yanıtta bir kelime arar.
• TCP Port, Ping ve DNS HTTP konuşmayan servisleri kontrol eder.
• Push kendi işinizin (örneğin bir yedekleme betiğinin) bir adresi çağırmasını bekler ve çağrı zamanında gelmezse uyarır.

Heartbeat Interval değerini ayarlayın (60 saniye makul bir varsayılandır), tek seferlik dalgalanmalarda uyarı almamak için birkaç Retries belirleyin ve kaydedin. Sertifika süresi bildirimini açtığınızda HTTPS izleyicileri sertifikaların süresi dolmadan önce de sizi uyarır.

Son olarak bir durum sayfası. Status Pages bölümünü açın, New Status Page düğmesine tıklayın, bir ad ve bir kısa ad (slug) girin ve göstermek istediğiniz izleyicileri ekleyin. Sayfa https://status.example.com/status/your-slug adresinde herkese açıktır. Yalnızca seçtiğiniz izleyicileri gösterir; planlı çalışmaların kesinti gibi görünmemesi için Maintenance pencereleri de tanımlayabilirsiniz.

Yedekleme ve geri yükleme

Her şey data klasöründedir: SQLite veritabanı (veya gömülü MariaDB dosyaları), yüklenen logolar ve ayarlar. 2. sürüm eski JSON yedekleme özelliğini kaldırdı ve projenin taşıma rehberi, veri klasörünü yedeklemeyi desteklenen tek yöntem olarak gösterir. Veritabanı dosyalarının tutarlı olması için konteyneri durdurun, klasörü ve Compose dosyasını arşivleyin ve yeniden başlatın:

sudo mkdir -p /opt/backups
cd /opt/uptime-kuma
docker compose stop
sudo tar -czf /opt/backups/uptime-kuma-$(date +%F).tar.gz -C /opt/uptime-kuma compose.yaml data
docker compose start

İzleme, yedeğin sürdüğü birkaç saniye boyunca duraklar. Yedeği cron ile sakin bir saate planlayın ve arşivleri sunucunun dışına kopyalayın.

Geri yüklemek için yığını durdurun, mevcut verileri kenara taşıyın, arşivi açın ve yeniden başlatın:

cd /opt/uptime-kuma
docker compose down
sudo mv data data.old
sudo tar -xzf /opt/backups/uptime-kuma-2026-10-09.tar.gz -C /opt/uptime-kuma
docker compose up -d

Geri yüklenen kontrol panelinin izleyicilerinizi gösterdiğini doğruladıktan sonra data.old klasörünü silin.

Uptime Kuma güncelleme

Önce sürüm notlarını okuyun ve yukarıdaki gibi yedek alın. Ardından projenin güncelleme rehberinde anlatıldığı gibi yeni imajı çekin ve konteyneri yeniden oluşturun:

cd /opt/uptime-kuma
docker compose pull
docker compose up -d --force-recreate
docker compose logs -f

Bazı güncellemeler ilk başlatmada veritabanını taşır. 1. sürümden 2. sürüme geçiş heartbeat tablosunu yeniden yazar ve dakikalar, yavaş donanımda ve uzun geçmişte saatler sürebilir. Logları izleyin (Ctrl+C izlemeyi durdurur) ve taşıma sırasında konteyneri durdurmayın; işlem yarıda kesilirse yedeği geri yükleyip yeniden deneyin.

Sorun giderme

Bir izleyici DOWN gösteriyor ama site tarayıcınızda çalışıyor

Kontrol konteynerin içinden yapılır; bu yüzden Docker ağı, DNS veya hedefteki bir güvenlik duvarı farklı bir sonuç üretebilir. Projenin sorun giderme sayfası konteynerin içinden test etmeyi önerir:

docker compose exec uptime-kuma bash
apt update && apt --yes install curl
curl -I https://www.example.com

Konteyner kabuğundan çıkmak için exit yazın. Ayrıca bir izleyicideki localhost ve 127.0.0.1 adreslerinin sunucuyu değil konteynerin kendisini gösterdiğini unutmayın; bunun yerine herkese açık HTTPS adresini izleyin.

Yönetici parolasını unuttunuz

Parolayı projenin belgelediği şekilde komut satırından sıfırlayın. Konteynerde bir kabuk açın, sıfırlama betiğini çalıştırın ve sorulduğunda yeni bir parola girin:

docker compose exec uptime-kuma bash
npm run reset-password

Sayfa açılıyor ama dönen simgede kalıyor veya sürekli yeniden bağlanıyor

Tarayıcı WebSocket bağlantısını açamadı. Caddy bunu kendiliğinden halleder; Nginx kullanıyorsanız proxy_http_version 1.1 satırını ve Upgrade ile Connection başlıklarını ekleyin. Sitenin önündeki bir CDN'in veya güvenlik duvarının WebSocket'e izin verdiğini de kontrol edin.

database is locked gibi SQLite hataları veya bozuk veritabanı

Genellikle veri klasörü, projenin desteklemediği bir ağ dosya sistemi üzerindedir. data klasörünü yerel bir diske taşıyın, veritabanı hasarlıysa en son yedeği geri yükleyin ve her veri klasörü için tek bir Uptime Kuma konteyneri çalıştırın.

IPv6 izleyicileri hep başarısız oluyor

Docker ağlarında varsayılan olarak IPv6 yoktur; bu yüzden konteyner yalnızca IPv6 kullanan hedeflere ulaşamaz. Projenin sorun giderme sayfası enable_ipv6: true içeren bir Compose ağının nasıl ekleneceğini gösterir; alternatif olarak hedefin IPv4 adresini izleyebilirsiniz.

Sonraki adımlar

• Bu kurulumun arkasındaki dosya biçimini Docker Compose temelleri rehberinde öğrenin.
• Diğer uygulamaları da aynı şekilde Caddy ile HTTPS arkasına alın.
• Sunucunun kendisini Yeni bir Linux sunucusunu güvenli hale getirin rehberiyle güçlendirin.
• Kendiniz çalıştırabileceğiniz diğer araçlara self-hosted uygulamalar sayfasından göz atın.
• Tüm izleyici türleri ve ayarlar için Uptime Kuma wiki sayfalarını okuyun.