Umami analitik Docker Compose ve HTTPS ile nasıl kurulur

Umami, gizliliği ön planda tutan açık kaynaklı bir web analitiği aracıdır. Sayfa görüntülemelerini, ziyaretçileri, yönlendiren siteleri, cihazları, konumları ve özel olayları sade bir panelde gösterir; birkaç web sitesini tek bir küçük sunucudan izleyecek kadar hafiftir. Kendiniz barındırdığınız için toplanan veriler kendi PostgreSQL veritabanınızda kalır.

Bu rehber güncel ana sürüm olan Umami 3'ü, Umami deposundaki Compose dosyasını temel alarak Docker Compose ve PostgreSQL ile kurar. Umami yalnızca 127.0.0.1:3000 üzerinde dinler; hiçbir şey herkese açılmadan önce varsayılan yönetici parolasını bir SSH tüneli üzerinden değiştirirsiniz, ardından paneli Caddy ile HTTPS üzerinden yayınlar, bir web sitesi ve izleme kodunu ekler, yedekleme ile güncellemeleri ayarlarsınız.

Adım 1 — Proje klasörünü ve gizli değerleri oluşturun

Umami için sahibi kendi kullanıcınız olan bir klasör oluşturun ve üç gizli değer üretin: veritabanı parolası, Umami'nin kimlik doğrulama token'larını korumak için kullandığı APP_SECRET ve iki aşamalı doğrulama sırlarını şifreleyen, herhangi bir kullanıcı 2FA'yı açmadan önce ayarlanması gereken 64 karakterlik onaltılık anahtar TWO_FACTOR_ENCRYPTION_KEY:

sudo mkdir -p /opt/umami && sudo chown $USER:$USER /opt/umami
cd /opt/umami
echo "POSTGRES_PASSWORD=$(openssl rand -hex 24)" > .env
echo "APP_SECRET=$(openssl rand -hex 32)" >> .env
echo "TWO_FACTOR_ENCRYPTION_KEY=$(openssl rand -hex 32)" >> .env
chmod 600 .env
cat .env

Uzun rastgele değerler içeren üç satır görmelisiniz. Onaltılık değerler yalnızca harf ve rakam içerdiği için parola veritabanı adresinde kaçış karakteri gerekmeden kullanılabilir. Umami kullanılmaya başladıktan sonra APP_SECRET ve TWO_FACTOR_ENCRYPTION_KEY değerlerini değiştirmeyin.

Adım 2 — Compose dosyasını yazın

docker-compose.yml dosyasını oluşturun:

nano /opt/umami/docker-compose.yml

Aşağıdaki dosya Umami deposundaki docker-compose.yml dosyasını iki değişiklikle izler: gizli değerler yer tutucular yerine .env dosyasından gelir ve 3000 portu yalnızca 127.0.0.1 üzerinde yayınlanır:

services:
  umami:
    image: ghcr.io/umami-software/umami:latest
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      DATABASE_URL: postgresql://umami:${POSTGRES_PASSWORD}@db:5432/umami
      APP_SECRET: ${APP_SECRET}
      TWO_FACTOR_ENCRYPTION_KEY: ${TWO_FACTOR_ENCRYPTION_KEY}
    depends_on:
      db:
        condition: service_healthy
    init: true
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "curl http://localhost:3000/api/heartbeat"]
      interval: 5s
      timeout: 5s
      retries: 5
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - umami-db-data:/var/lib/postgresql/data
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  umami-db-data:

ghcr.io/umami-software/umami:latest imajı depodaki dosyanın kullandığı imajdır; Umami belgeleri aynı imajı docker.umami.is/umami-software/umami:latest adıyla da yayınlar. Compose'un dosyayı ve gizli değerleri okuduğunu kontrol edin:

cd /opt/umami
docker compose config --quiet && echo "compose file OK"

Adım 3 — Umami'yi başlatın

docker compose up -d
docker compose ps
docker compose logs umami --tail 30

İki konteyner de çalışır durumda görünmeli ve birkaç saniye sonra healthy olmalıdır. Umami ilk başlatmada tablolarını ve varsayılan yönetici hesabını oluşturur. Sağlık kontrolünün kullandığı heartbeat uç noktasını kontrol edin:

curl -i http://127.0.0.1:3000/api/heartbeat

HTTP/1.1 200 OK yanıtı almalısınız. umami konteyneri sürekli yeniden başlıyorsa logları okuyun; en yaygın neden yanlış veritabanı parolasıdır (Sorun giderme bölümüne bakın).

Adım 4 — Yayına almadan önce varsayılan girişi değiştirin

Her yeni Umami kurulumu admin kullanıcı adı ve umami parolasıyla başlar. Panel internetten erişilebilir olmadan önce bunu değiştirin. Kendi bilgisayarınızdan sunucuya bir SSH tüneli açın:

ssh -L 3000:127.0.0.1:3000 your-user@203.0.113.10

Bu oturumu açık tutun ve bilgisayarınızda http://localhost:3000 adresine gidin. admin kullanıcısı ve umami parolasıyla giriş yapın, yan menüdeki profil düğmesine tıklayın, Settings → Profile bölümünü açın ve Change password düğmesine tıklayın. Uzun ve benzersiz bir parola kullanın. Security sekmesinde iki aşamalı doğrulamayı da açabilirsiniz; TWO_FACTOR_ENCRYPTION_KEY ayarlı olduğu için bu özellik çalışır. İşiniz bitince tüneli kapatın.

Adım 5 — Umami'yi Caddy ile HTTPS üzerinden sunun

/etc/caddy/Caddyfile dosyasına bir site bloğu ekleyin:

analytics.example.com {
    reverse_proxy 127.0.0.1:3000
}

Caddy'yi yeniden yükleyin, giriş sayfasını kontrol edin ve güvenlik duvarının yalnızca SSH ve web trafiğine izin verdiğinden emin olun:

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

Caddy ziyaretçinin adresini Umami'ye X-Forwarded-For başlığıyla iletir; Umami tekil ziyaretçiler ve konumlar için bu bilgiye ihtiyaç duyar. Önüne standart dışı bir başlık kullanan başka bir proxy veya CDN koyarsanız CLIENT_IP_HEADER değerini o başlığın adına ayarlayın. Caddy'ye alternatif olarak Nginx (Nginx ve Certbot) ve Traefik (Traefik) de kullanılabilir.

Adım 6 — Bir web sitesi ve izleme kodu ekleyin

https://analytics.example.com adresinde giriş yapın, kenar çubuğunda Websites öğesini seçin ve Add website düğmesine tıklayın. Bir Name ve sitenin gerçek Domain değerini girin (Umami bunu kendi sitenizi yönlendiren siteler listesinden çıkarmak için kullanır), ardından Save düğmesine tıklayın.

Yeni web sitesini açın, Edit düğmesine tıklayın ve Tracking code bölümünü bulun. Kodu kopyalayın ve izlemek istediğiniz her sayfanın head bölümüne yapıştırın. Kendi web sitesi kimliğinizle buna benzer görünür:

<script defer src="https://analytics.example.com/script.js" data-website-id="your-website-id"></script>

Sitenizi bir tarayıcıda açın, ardından Umami'de web sitesinin panelini kontrol edin: ziyaret birkaç saniye içinde görünmelidir. Betik isteğe bağlı data- öznitelikleri kabul eder; örneğin yalnızca listelenen sunucu adlarını izlemek için data-domains, sorgu dizelerini atmak için data-exclude-search ve tarayıcının Do Not Track ayarına uymak için data-do-not-track.

Adım 7 — İzleme betiğini reklam engelleyiciler için yeniden adlandırın (isteğe bağlı)

Birçok reklam engelleyici bilinen analitik sunucularındaki script.js ve /api/send isteklerini engeller. Kendi sunucunuzdaki kurulumda ikisini de ortam değişkenleriyle yeniden adlandırabilirsiniz. Bunları docker-compose.yml içindeki umami servisinin environment: bölümüne ekleyin:

      TRACKER_SCRIPT_NAME: insights.js
      COLLECT_API_ENDPOINT: /api/insights

Değişikliği uygulayın ve izleme kodunuzdaki src değerini https://analytics.example.com/insights.js olarak güncelleyin. İzleme betiği verilerini yeni uç noktaya kendiliğinden gönderir:

docker compose up -d
curl -I https://analytics.example.com/insights.js

Diğer yararlı çalışma zamanı değişkenleri arasında IGNORE_IP (ofisiniz gibi hariç tutulacak IP adresleri veya aralıkları), DISABLE_TELEMETRY ve DISABLE_UPDATES bulunur.

Yedekleme ve geri yükleme

Kullanıcılar, web siteleri ve olaylar dahil Umami'nin sakladığı her şey PostgreSQL'dedir. Veritabanını düzenli olarak dökün ve Compose dosyası ile .env dosyasını da yanında saklayın:

sudo mkdir -p /opt/backups && sudo chown $USER:$USER /opt/backups && chmod 700 /opt/backups
cd /opt/umami
docker compose exec -T db pg_dump -U umami -Fc umami > /opt/backups/umami-db-$(date +%F).dump
tar czf /opt/backups/umami-config-$(date +%F).tar.gz -C /opt/umami docker-compose.yml .env
ls -lh /opt/backups

Dosyaları sunucunun dışına kopyalayın ve bir test geri yüklemesi başarılı olduktan sonra komutları cron ile zamanlayın. Geri yüklemek için docker-compose.yml ve .env dosyalarını /opt/umami içine geri koyun, ardından dökümü boş bir veritabanına yükleyin:

cd /opt/umami
docker compose stop umami
docker compose up -d --wait db
docker compose exec -T db dropdb -U umami --if-exists umami
docker compose exec -T db createdb -U umami umami
docker compose exec -T db pg_restore -U umami -d umami < /opt/backups/umami-db-2026-10-09.dump
docker compose up -d

Kendi yedek dosyanızın tarihini kullanın. Giriş yapın ve web sitelerinizin ve istatistiklerinizin geri geldiğini doğrulayın.

Umami güncelleme

Önce sürüm notlarını okuyun ve bir veritabanı yedeği alın. Ardından Umami'nin Docker Compose için belgelediği güncelleme yöntemini izleyin:

cd /opt/umami
docker compose pull
docker compose up --force-recreate -d
docker compose logs umami --tail 30

Veritabanı geçişleri yeni konteyner başlarken kendiliğinden çalışır. Bir ana sürüm yükseltmesinden sonra Umami, PostgreSQL'in sorgu planlayıcı istatistiklerini yenilemesi için ANALYZE çalıştırmayı önerir; bu yapılmazsa büyük kurulumlarda panel sorguları yavaşlayabilir:

docker compose exec db psql -U umami -d umami -c 'ANALYZE;'

Bir sürüm etiketi sabitlediyseniz çekmeden önce docker-compose.yml içinde değiştirin. image: satırındaki PostgreSQL ana sürümünü döküm alıp geri yüklemeden değiştirmeyin; daha yeni bir PostgreSQL ana sürümü eski veri dizinini doğrudan açamaz.

Sorun giderme

umami konteyneri sürekli yeniden başlıyor veya unhealthy kalıyor

docker compose logs umami --tail 50 çıktısını okuyun. umami kullanıcısı için kimlik doğrulamanın başarısız olduğunu bildiriyorsa veritabanı volume'u .env içindekinden farklı bir parolayla oluşturulmuştur. PostgreSQL parolayı yalnızca ilk başlatmada ayarlar; veri içermeyen yeni bir kurulumda volume'u docker compose down -v ile silin ve yeniden başlatın.

Bazı tarayıcılardan gelen ziyaretler hiç görünmüyor

Bir reklam engelleyici veya gizlilik eklentisi betiği ya da veri toplama isteğini engelliyor. Sitenizde tarayıcının geliştirici araçlarını açın ve script.js veya /api/send adreslerine giden engellenmiş istekleri arayın. Adım 7'de gösterildiği gibi ikisini de yeniden adlandırın. data-domains ayarladıysanız www ile veya www olmadan tam sunucu adını içerdiğini de kontrol edin.

Tüm ziyaretçiler aynı yerden geliyormuş gibi görünüyor

Umami ziyaretçinin değil, proxy'nin adresini görüyor. İsteklerin Umami'ye yalnızca Caddy üzerinden 127.0.0.1:3000 adresine ulaştığından emin olun; önünde bir CDN veya başka bir proxy varsa CLIENT_IP_HEADER değerini onun istemci adresi için kullandığı başlığa ayarlayın.

İki aşamalı doğrulama açılamıyor

TWO_FACTOR_ENCRYPTION_KEY eksik veya boş. .env dosyasının 64 karakterlik onaltılık bir değer içerdiğini ve docker-compose.yml dosyasının bunu umami servisine ilettiğini kontrol edin, ardından docker compose up -d komutunu çalıştırın.

Caddy 502 Bad Gateway döndürüyor

Umami 127.0.0.1:3000 üzerinde yanıt vermiyor. /opt/umami içinde docker compose ps çalıştırın; umami servisi veritabanı sağlık kontrolünü beklediği için hata veren bir db konteyneri onu da kapalı tutar.

Sonraki adımlar

• Kapsamlı bir analitik paketiyle karşılaştırın: Matomo nasıl kurulur.
• Başka bir hafif seçeneği deneyin: Plausible Community Edition.
• Aynı proxy arkasında başka uygulamalar barındırmak için Caddy ile reverse proxy rehberini kullanın.
• Kendi sunucunuzda analitik için sunucuları web analitiği hosting sayfasında inceleyin.
• Olayları, raporları ve API'yi Umami belgelerinde keşfedin.