Uptime Kuma Docker ile Kurulum ve Yapılandırma

Yazar:komut.io ekibi Uptime Kuma ile Servis ve Web Sitesi İzleme
0 Yorum

Monitoring dünyasında güzel bir yer var: açık kaynaklı, hafif, kullanımı kolay ve görsel olarak tatmin edici araçlar. Uptime Kuma tam olarak bu kategoriye giriyor. Zabbix veya Prometheus gibi devasa yapılar kurmak zorunda kalmadan, servislerinizi ve web sitelerinizi izlemek istiyorsanız, Uptime Kuma gerçekten işe yarayan bir çözüm. Ben de bu yazıda sizi sıfırdan çalışan bir Uptime Kuma kurulumuna götüreceğim; Docker üzerinde, production ortamına yakın bir yapıyla.

Uptime Kuma Nedir, Neden Tercih Edilir?

Uptime Kuma, Node.js tabanlı, self-hosted bir uptime monitoring aracıdır. Fancy bir arayüzü var, bildirim sistemi oldukça gelişmiş ve kurulumu inanılmaz derecede basit. Betterstack (eski adıyla Logtail/Uptime) gibi SaaS çözümlerine para vermek istemeyenler veya verilerini dışarıya çıkarmak istemeyenler için mükemmel bir alternatif.

Desteklediği izleme tipleri arasında şunlar var:

  • HTTP/HTTPS: Web sitesi ve API endpoint izleme
  • TCP Port: Herhangi bir TCP servisi (veritabanı, SSH, vs.)
  • Ping: ICMP ping ile sunucu erişilebilirlik kontrolü
  • DNS: DNS kayıt çözümleme kontrolü
  • Docker Container: Container sağlık durumu izleme
  • Steam Game Server: Oyun sunucusu izleme (ilginç ama var işte)
  • MQTT: IoT projelerinde faydalı

Bildirim kanalları konusunda da gerçekten zengin: Telegram, Slack, Discord, PagerDuty, Webhook, E-posta, Gotify ve daha onlarca entegrasyon mevcut.

Gereksinimler

Kuruluma geçmeden önce ortamı hazırlayalım. Bu rehberde şunları varsayıyorum:

  • Ubuntu 22.04 LTS veya Debian 12 üzerinde çalışıyorsunuz
  • Docker ve Docker Compose kurulu
  • Tercihen bir domain adı veya en azından statik IP mevcut
  • Reverse proxy için Nginx kullanacağız

Docker ve Docker Compose kurulu değilse hızlıca geçelim:

# Docker kurulumu
curl -fsSL https://get.docker.com | sh

# Kullanıcıyı docker grubuna ekle (sudo olmadan çalıştırmak için)
sudo usermod -aG docker $USER
newgrp docker

# Docker Compose plugin kontrolü
docker compose version

Docker Compose ile Kurulum

En temiz yol Docker Compose kullanmak. Doğrudan docker run ile de çalıştırabilirsiniz ama compose dosyası ileride yapılandırmayı güncellemeyi çok daha kolay hale getiriyor.

Önce çalışma dizinimizi oluşturalım:

mkdir -p /opt/uptime-kuma
cd /opt/uptime-kuma

Şimdi docker-compose.yml dosyamızı oluşturalım:

cat > docker-compose.yml << 'EOF'
version: '3.8'

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    restart: unless-stopped
    volumes:
      - uptime-kuma-data:/app/data
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "3001:3001"
    environment:
      - UPTIME_KUMA_PORT=3001
    networks:
      - monitoring

volumes:
  uptime-kuma-data:
    driver: local

networks:
  monitoring:
    driver: bridge
EOF

Burada /var/run/docker.sock mount ediyoruz çünkü Docker container izleme özelliğini kullanmak istiyorsanız bu gerekli. Eğer container izleme kullanmayacaksanız o satırı kaldırabilirsiniz. Güvenlik açısından ro (read-only) olarak mount etmek önemli.

Servisi başlatalım:

docker compose up -d

# Logları takip edelim
docker compose logs -f

Bir iki dakika bekledikten sonra http://sunucu-ip:3001 adresine giderek arayüze erişebilirsiniz. İlk girişte admin kullanıcısı oluşturmanız istenecek.

Nginx Reverse Proxy Yapılandırması

Port 3001 ile dışarıya açmak production ortamda pek şık olmaz. Nginx arkasına alalım ve HTTPS ekleyelim.

# Nginx kurulumu
sudo apt install -y nginx certbot python3-certbot-nginx

# Site yapılandırması
sudo nano /etc/nginx/sites-available/uptime-kuma

Nginx yapılandırma dosyası:

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;
    server_name status.sirketiniz.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name status.sirketiniz.com;

    ssl_certificate /etc/letsencrypt/live/status.sirketiniz.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/status.sirketiniz.com/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;

    # Uptime Kuma websocket için kritik
    location / {
        proxy_pass         http://localhost:3001;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection $connection_upgrade;
        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 3600s;
        proxy_send_timeout 3600s;
    }
}

WebSocket desteği burada kritik. Uptime Kuma gerçek zamanlı güncellemeler için WebSocket kullanıyor. proxy_read_timeout ve proxy_send_timeout değerlerini 3600 saniye yapmazsan bağlantı kesiliyor ve arayüz donmuş gibi görünüyor. Bu tip sorunlarla karşılaşırsanız ilk bakılacak yer burası.

# Site aktif et
sudo ln -s /etc/nginx/sites-available/uptime-kuma /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

# SSL sertifikası al
sudo certbot --nginx -d status.sirketiniz.com

İlk Monitor Ekleme

Arayüze girdikten sonra “Add New Monitor” butonuyla izleme eklemeye başlayabilirsiniz. Birkaç gerçek dünya senaryosu üzerinden gidelim.

Senaryo 1: E-ticaret Sitesi İzleme

Bir e-ticaret sitesini izlerken sadece “site açık mı” kontrolü yetmez. Arama fonksiyonu, ödeme sayfası, API endpoint gibi kritik noktaları ayrı ayrı izlemek gerekir.

Tipik bir yapılandırma şöyle olur:

  • Monitor Type: HTTP(s)
  • Friendly Name: Ana Sayfa – HTTPS Kontrolü
  • URL: https://magazam.com
  • Heartbeat Interval: 60 saniye
  • Retries: 3 (üst üste 3 başarısız olursa alarm ver)
  • HTTP Options > Expected Status Codes: 200
  • HTTP Options > Keyword: Sitenizde mutlaka olması gereken bir metin (örneğin site adı veya copyright metni)

Keyword özelliği çok değerli. Site yanıt verse bile içerik bozuksa (beyaz ekran, hata sayfası) bunu yakalamak için keyword mutlaka kullanın.

Senaryo 2: Veritabanı Port Kontrolü

Veritabanı sunucunuz ayakta mı diye kontrol etmek için TCP monitor kullanırız:

  • Monitor Type: TCP Port
  • Friendly Name: PostgreSQL – Prod DB
  • Hostname: 10.0.1.50
  • Port: 5432
  • Heartbeat Interval: 30 saniye

Dikkat: Bu kontrol sadece port dinlenip dinlenmediğini kontrol eder, veritabanının gerçekten sağlıklı olduğunu değil. Daha derin kontrol için Uptime Kuma’nın database monitor özelliğini veya ayrı bir monitoring katmanı kullanmanız gerekir.

Senaryo 3: SSL Sertifika İzleme

Uptime Kuma, HTTPS monitörlerinde SSL sertifika süresini otomatik takip eder. “Certificate Expiry Notification” özelliğini açarsanız sertifika dolmadan X gün önce bildirim alırsınız. Bunu aktif etmeyi unutmayın; production’da sertifika bittiği için site düşmesi gerçekten yaşanan ve utandırıcı bir durum.

Bildirim Sistemi Yapılandırması

Uptime Kuma’nın en güçlü taraflarından biri bildirim sistemi. Telegram en yaygın kullanılan kanal olduğundan onunla başlayalım.

Telegram Bot Kurulumu

  1. Telegram’da @BotFather ile konuşun ve /newbot komutuyla yeni bir bot oluşturun
  2. Bot token’ınızı alın (şuna benzer: 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz)
  3. Botunuzu bir gruba ekleyin veya direkt mesaj için Chat ID’nizi alın

Chat ID almak için:

# Bota bir mesaj gönderdikten sonra bu URL ile chat ID'nizi alabilirsiniz
curl "https://api.telegram.org/bot<TOKEN>/getUpdates" | python3 -m json.tool

Uptime Kuma arayüzünde “Settings > Notifications > Add Notification” yolunu izleyin, Telegram seçin, token ve chat ID’yi girin.

Webhook ile Özel Entegrasyon

Bazen şirket içi sistemlere bildirim göndermek gerekiyor. Webhook ile bu çok kolay:

# Basit bir webhook receiver (test için)
# webhook-test.py
from http.server import HTTPServer, BaseHTTPRequestHandler
import json

class WebhookHandler(BaseHTTPRequestHandler):
    def do_POST(self):
        content_length = int(self.headers['Content-Length'])
        body = self.rfile.read(content_length)
        data = json.loads(body)
        
        print(f"Monitor: {data.get('monitor', {}).get('name')}")
        print(f"Status: {'UP' if data.get('heartbeat', {}).get('status') == 1 else 'DOWN'}")
        
        self.send_response(200)
        self.end_headers()

HTTPServer(('0.0.0.0', 8888), WebhookHandler).serve_forever()

Uptime Kuma’nın gönderdiği webhook payload’ı şu yapıya sahip: monitor bilgileri, heartbeat durumu, zaman damgası ve tag’ler. Bu veriyi alıp kendi ticket sisteminize, Jira’ya veya herhangi bir araca iletebilirsiniz.

Status Page Oluşturma

Uptime Kuma’nın önemli özelliklerinden biri de genel erişime açık status page desteği. Müşterilerinize veya ekibinize “tüm sistemler yeşil” ya da hangi servisin sorunlu olduğunu göstermek için kullanabilirsiniz.

“Status Pages” menüsünden yeni bir sayfa oluşturun. Şunları yapılandırabilirsiniz:

  • Slug: URL’de görünecek kısım (örneğin status -> status.sirketiniz.com/status)
  • Title ve Description: Müşterilere görünecek başlık
  • Monitor Seçimi: Hangi monitorlerin bu sayfada görünüeceği
  • Custom Domain: Ayrı bir domain atayabilirsiniz (örneğin status.sirketiniz.com)
  • Incident Notları: Manuel durum güncellemeleri yazabilirsiniz

Custom domain için Nginx yapılandırmasını güncellemek gerekir:

# Mevcut location bloğuna ekle
location /status/your-slug {
    proxy_pass http://localhost:3001/status/your-slug;
    # diğer proxy direktifleri...
}

Yedekleme ve Veri Kalıcılığı

Uptime Kuma tüm verisini SQLite dosyasında tutuyor. Docker volume kullandığımız için container silinse bile veriler korunuyor ama ek yedekleme almak iyi pratik.

#!/bin/bash
# /opt/scripts/backup-uptime-kuma.sh

BACKUP_DIR="/backup/uptime-kuma"
DATE=$(date +%Y%m%d_%H%M%S)
VOLUME_PATH=$(docker volume inspect uptime-kuma_uptime-kuma-data --format '{{ .Mountpoint }}')

mkdir -p "$BACKUP_DIR"

# SQLite veritabanını yedekle
cp "$VOLUME_PATH/kuma.db" "$BACKUP_DIR/kuma_$DATE.db"

# 7 günden eski yedekleri sil
find "$BACKUP_DIR" -name "*.db" -mtime +7 -delete

echo "Yedekleme tamamlandi: kuma_$DATE.db"

Bu scripti cron’a ekleyelim:

chmod +x /opt/scripts/backup-uptime-kuma.sh

# Her gece 02:00'de yedek al
crontab -e
# Şu satırı ekle:
0 2 * * * /opt/scripts/backup-uptime-kuma.sh >> /var/log/uptime-kuma-backup.log 2>&1

Yedekten geri yükleme de basit: container’ı durdurun, kuma.db dosyasını volume’e kopyalayın, container’ı başlatın.

Güncelleme Prosedürü

Uptime Kuma sık güncelleme alıyor. Docker ile güncelleme çok temiz:

cd /opt/uptime-kuma

# Yeni image'ı çek
docker compose pull

# Container'ı yeniden başlat
docker compose up -d

# Eski image'ları temizle
docker image prune -f

1 tag’ini kullandığımız için her zaman en son 1.x sürümüne geçiyoruz. Daha kontrollü bir yapı istiyorsanız spesifik sürüm tag’i kullanın: louislam/uptime-kuma:1.23.13 gibi.

Sorun Giderme

Karşılaştığım yaygın sorunlar ve çözümleri:

Container başlamıyor:

# Log kontrol
docker compose logs uptime-kuma

# Yaygın neden: port çakışması
sudo ss -tlnp | grep 3001

Arayüz donuyor veya bağlantı kesiliyor: WebSocket timeout sorunudur. Nginx yapılandırmasında proxy_read_timeout ve proxy_send_timeout değerlerini kontrol edin. Eğer Cloudflare kullanıyorsanız WebSocket’lerin etkinleştirildiğinden emin olun.

Docker container izleme çalışmıyor: /var/run/docker.sock mount edilmeli ve Uptime Kuma container’ının bu sokete erişim izni olmalı:

# Docker socket grubunu kontrol et
ls -la /var/run/docker.sock

# Eğer gerekirse izin ver
sudo chmod 666 /var/run/docker.sock
# NOT: Bu güvenlik açısından ideal değil, production'da docker grubunu kullanmak daha doğru

Yüksek CPU kullanımı: Çok fazla monitor varsa ve heartbeat interval’ları çok kısaysa CPU yükü artabilir. 50’den fazla monitor için interval’ları 60 saniyenin altına indirmeyin.

Production Ortamı için Ek Öneriler

Canlı ortamda dikkat etmem gerektiğini zamanla öğrendiğim birkaç şey:

  • Uptime Kuma’yı izlenecek sistemlerden farklı bir sunucuda çalıştırın. Aynı sunucuda olursa, sunucu düştüğünde monitoring de düşer ve haberiniz olmaz.
  • Birden fazla lokasyon kullanın. Mümkünse farklı datacenter veya cloud region’da ikinci bir Uptime Kuma instance kurun.
  • Tag sistemi kullanın. Monitorlarınızı production, staging, database, api gibi tag’lerle organize edin. Onlarca monitor olduğunda filtreleme hayat kurtarır.
  • Maintenance window tanımlayın. Planlı bakım sırasında false alarm almamak için “Maintenance” özelliğini kullanın. Settings > Maintenance > Add Maintenance ile bakım penceresi tanımlayabilirsiniz.
  • Proxy/VPN arkasındaki servisleri izlemek için Uptime Kuma’nın proxy desteğini kullanın. Settings > Proxies bölümünden SOCKS5 veya HTTP proxy tanımlayabilirsiniz.

Sonuç

Uptime Kuma, monitoring ihtiyaçlarının büyük çoğunluğunu karşılayan, kurulumu ve bakımı kolay bir araç. Zabbix veya Prometheus ile kıyas yapmak doğru olmaz; onlar çok daha derin metrik toplama ve analiz yapabilir ama bunun bedeli karmaşıklıktır. Uptime Kuma’nın vaadi basit ve net: servisleriniz ayakta mı, değil mi, düşerse haber ver.

Küçük ve orta ölçekli altyapılar için, hatta büyük altyapıların “ilk katman” kontrol mekanizması olarak, Uptime Kuma mükemmel bir araç. Docker ile birkaç dakikada kurulabiliyor olması, düşük kaynak tüketimi ve güçlü bildirim sistemi onu gerçekten değerli kılıyor.

Bu yazıdaki kurulumu yaptıktan sonra üzerine inşa edebileceğiniz şeyler var: Prometheus metrics endpoint’i (/metrics) aktif ederek Grafana ile entegre edebilir, API’sini kullanarak kendi otomasyon scriptlerinizi yazabilirsiniz. Ama önce çalışan, basit bir kurulum yapın, üretimde birkaç hafta kullanın, ihtiyaçlarınızı görün, sonra geliştirin.

Bir yanıt yazın

E-posta adresiniz yayınlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir