Umami Analytics Kurulumu: Docker, PostgreSQL, Nginx ve KVKK Notları

Umami nedir, kimler için uygundur?

Umami, GitHub: umami-software/umami deposunda MIT lisansıyla yayımlanan açık kaynaklı bir projedir. Ticari kullanım dahil kendi sunucunuzda ücretsiz çalıştırabilirsiniz. Şirketin ayrıca barındırılan (bulut) bir sürümü de vardır; bu yazı yalnızca kendi kurduğunuz sürümü anlatır. 1 Kasım 2026 itibarıyla GitHub'daki son sürüm v3.4.1'dir.

• Birkaç site veya projenin trafiğini tek panelde görmek isteyen ajanslar ve geliştiriciler.
• Ziyaretçi verisini üçüncü taraf bir analitik sağlayıcısına göndermek istemeyen site sahipleri.
• Temel metriklerle yetinen, karmaşık reklam ve dönüşüm raporlarına ihtiyaç duymayan ekipler.

Kapsamlı reklam entegrasyonu, kitle segmentasyonu veya Google Ads bağlantısı gibi ihtiyaçlarınız varsa Umami bunların yerini tutmaz. Analitik araçlar arasındaki veri farklarına dair genel bir bakış için GA4 ve Search Console veri farkı yazısına da göz atabilirsiniz.

Gereksinimler ve veritabanı: artık yalnızca PostgreSQL

Kurulum belgesine (Umami Docs: Installation) göre güncel gereksinimler şunlardır:

Minimum RAM veya CPU değeri resmî belgede yer almıyor; bu yüzden burada bir rakam vermiyoruz. Kurulumdan sonra sunucu izleme temelleri yazısındaki yöntemlerle bellek ve disk kullanımını takip edin. PostgreSQL hakkında genel bilgi için PostgreSQL nedir yazısına bakabilirsiniz.

1. Adım: Docker ve proje klasörü

Sunucunuzda Docker Engine ve Compose eklentisinin kurulu olduğunu varsayıyoruz; değilse Docker Compose başlangıç rehberi yazısını izleyin. Ardından bir proje klasörü ve rastgele anahtarlar oluşturun. Belge, APP_SECRET ve TWO_FACTOR_ENCRYPTION_KEY için openssl rand -hex 32 komutunu öneriyor:

sudo mkdir -p /opt/umami && cd /opt/umami

# Her biri 64 karakterlik hex anahtar uretir
openssl rand -hex 32   # APP_SECRET icin
openssl rand -hex 32   # TWO_FACTOR_ENCRYPTION_KEY icin

Bu değerleri ve veritabanı şifresini bir .env dosyasına yazın. Dosyayı yalnızca root okuyabilsin:

# /opt/umami/.env
POSTGRES_PASSWORD=GUCLU_BIR_SIFRE
APP_SECRET=OPENSSL_CIKTISI_1
TWO_FACTOR_ENCRYPTION_KEY=OPENSSL_CIKTISI_2

sudo chmod 600 /opt/umami/.env

2. Adım: docker-compose.yml

Aşağıdaki dosya, Umami deposundaki docker-compose.yml esas alınarak hazırlandı. Yaptığımız değişiklikler şunlar: sabit şifreler yerine .env değişkenleri kullanıldı ve port yalnızca 127.0.0.1 üzerinden yayımlandı. İmaj adı olarak kurulum belgesindeki docker.umami.is/umami-software/umami kullanıldı; depodaki örnek dosya aynı projenin ghcr.io/umami-software/umami imajını kullanıyor, ikisi de resmîdir.

services:
  umami:
    image: docker.umami.is/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:

cd /opt/umami
sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs -f umami

Konteyner ilk açılışta tabloları ve varsayılan yönetici hesabını oluşturur. docker compose ps çıktısında umami servisi healthy görünene kadar bekleyin. Veritabanının UTC kullandığını şu komutla doğrulayabilirsiniz:

sudo docker compose exec db psql -U umami -d umami -c 'SHOW timezone;'

3. Adım: Nginx ve Let's Encrypt

analiz.example.com gibi bir alt alan adının A kaydını sunucu IP'nize yönlendirin. Nginx tarafında basit bir ters vekil yeterli; mantığını reverse proxy nedir ve Nginx server block rehberi yazılarında anlattık.

# /etc/nginx/sites-available/umami
server {
    listen 80;
    server_name analiz.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        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;
    }
}

sudo ln -s /etc/nginx/sites-available/umami /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d analiz.example.com

Certbot kurulumu ve otomatik yenileme ayrıntıları Let's Encrypt SSL kurulumu yazısında. Sitenizin önünde Cloudflare gibi bir vekil varsa veya panelde konumlar hep aynı görünüyorsa, belgede tanımlı TRUSTED_PROXIES (örneğin loopback, private ön ayarları) ve CLIENT_IP_HEADER değişkenlerine bakın (Umami Docs: Environment variables). Gerçek ziyaretçi IP'si konusu için Cloudflare arkasında gerçek ziyaretçi IP'si yazısı da yardımcı olur.

4. Adım: İlk giriş ve yönetici güvenliği

Umami Docs: Login sayfasına göre varsayılan kurulum admin kullanıcı adı ve umami şifresiyle bir yönetici hesabı oluşturur. Bu bilgiler herkesçe bilindiği için ilk iş şifreyi değiştirin:

• https://analiz.example.com adresinden admin / umami ile giriş yapın.
• Yan menüdeki profil düğmesinden Settings, ardından Profile bölümüne geçip şifreyi değiştirin. Güçlü bir şifre için güçlü şifre rehberine bakın.
• Security sekmesinden iki adımlı doğrulamayı açın. Bunun için TWO_FACTOR_ENCRYPTION_KEY değişkeninin tanımlı olması gerekir; belgeye göre bu anahtar olmadan hiçbir kullanıcı 2FA açamaz.
• Ekip arkadaşlarına kendi hesaplarını açın; yönetici hesabını paylaşmayın.

5. Adım: Siteyi ekleyin ve izleme kodunu yerleştirin

Panelde yan menüden Websites bölümünü açın, sağ üstteki ekleme düğmesiyle bir site oluşturun. Alan adını sitenizin gerçek adresiyle yazın; Umami bu bilgiyi kendi sitenizi yönlendiren istatistiklerinden ayırmak için kullanır. Sonra sitenin Edit düğmesine tıklayın; kod Tracking code bölümündedir (Umami Docs: Collect data). Kodu sitenizin <head> bölümüne ekleyin. Genel biçimi şöyledir:

<script
  defer
  src="https://analiz.example.com/script.js"
  data-website-id="PANELDEKI-WEBSITE-ID"
  data-domains="www.example.com"
></script>

Sık kullanılan veri öznitelikleri (Umami Docs: Tracker configuration):

Next.js kullanıyorsanız belge düz <script> yerine next/script bileşenini öneriyor. Kodu ekledikten sonra sitenizi açın ve tarayıcıdaki geliştirici araçlarının Network sekmesinde Umami adresinize istek gittiğini kontrol edin. Reklam engelleyiciler betiği engelleyebilir; belge betik adını ve toplama uç noktasını değiştirmek için TRACKER_SCRIPT_NAME ve COLLECT_API_ENDPOINT değişkenlerini tanımlar. Kendi ofis IP'nizi istatistik dışında tutmak için IGNORE_IP değişkeni vardır.

Çerezler ve KVKK: dikkatli olun

Umami'nin SSS sayfası (Umami Docs: FAQ) izleme betiğinin çerez kullanmadığını söyler. Aynı sayfa, bir çerez bildirimine ihtiyaç olup olmadığının kullandığınız diğer hizmetlere ve geçerli gerekliliklere bağlı olduğunu, uyumluluğun da aracı nasıl yapılandırıp kullandığınıza bağlı olduğunu ekler. Yani belge bir uyumluluk garantisi vermez.

• Çerez olmaması, kişisel veri işlenmediği anlamına gelmez. Sunucunuz her istekte ziyaretçinin IP adresini ve tarayıcı bilgisini alır; Umami yaklaşık konumu da bu isteklerden çıkarır.
• Aydınlatma yükümlülüğü ayrıca değerlendirilmelidir. Hangi verinin hangi amaçla işlendiğini çerez veya gizlilik metninizde açıklayın.
• Diğer araçlar durumu değiştirir. Sitenizde reklam pikselleri, gömülü videolar veya başka analitik kodlar varsa çerez bandı ihtiyacı bunlardan doğabilir.
• Veri sizde kalır, ama sorumluluk da sizdedir. Sunucu güvenliği, yedeklerin korunması ve saklama süresi sizin kararınızdır.

KVKK'nın çerez rehberine göre birinci taraf analitiğin hangi koşullarda açık rıza gerektirmeyebileceğini ve bandın nasıl kurulacağını çerez politikası ve çerez bandı nasıl hazırlanır yazısında ayrıntılı anlattık. Umami kurmak tek başına sizi bu değerlendirmeden muaf kılmaz; emin değilseniz bir hukukçuya danışın.

Güncelleme

Umami Docs: Updates sayfasındaki Docker Compose adımları şunlardır:

cd /opt/umami
sudo docker compose pull
sudo docker compose up --force-recreate -d

Belge, v3 gibi büyük bir yükseltmeden sonra sorgu istatistiklerini tazelemek için PostgreSQL'de ANALYZE; çalıştırılabileceğini ve bunun canlı veritabanında güvenli olduğunu belirtir. Güncellemeden önce mutlaka aşağıdaki yedeği alın.

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

Yedekleme

Tüm istatistikler PostgreSQL'dedir. Uygulama konteynerinin kendisi durumsuzdur; asıl korunması gereken veritabanı ve .env dosyasıdır.

# Yedek al (cron icin -T bayragi TTY ayirmaz)
cd /opt/umami
sudo docker compose exec -T db pg_dump -U umami umami | gzip > /root/yedek/umami-$(date +%F).sql.gz

# Geri yukleme (bos bir veritabanina)
gunzip -c /root/yedek/umami-2026-11-01.sql.gz | sudo docker compose exec -T db psql -U umami -d umami

Yedekleri aynı sunucuda bırakmayın; rsync ile sunucu yedekleme ve veritabanı yedekleme stratejileri yazılarındaki gibi başka bir konuma taşıyın, zamanlamak için cron kullanın.

Sık karşılaşılan sorunlar

Sık Sorulan Sorular

Umami MySQL ile çalışır mı?

Güncel v3 serisi çalışmaz. v3.0.0 sürüm notları MySQL desteğinin kaldırıldığını ve yalnızca PostgreSQL desteklendiğini söylüyor. MySQL kullanan eski kurulumlar için projenin taşıma kılavuzu var.

Umami kullanınca çerez bandına gerek kalmaz mı?

Bunu genel olarak söylemek doğru olmaz. Umami'nin betiği çerez kullanmıyor, ancak IP adresi gibi veriler yine işleniyor ve sitenizdeki diğer araçlar bant ihtiyacı doğurabilir. Aydınlatma metni her durumda gündemde kalır; değerlendirmeyi kendi kurulumunuza göre yapın.

Minimum kaç GB RAM gerekir?

Resmî belge bir minimum RAM veya CPU değeri vermiyor. Küçük bir sunucuyla başlayıp bellek kullanımını izleyin; veritabanı büyüdükçe disk alanını da takip edin.

Birden fazla siteyi tek Umami'de izleyebilir miyim?

Evet. Websites bölümünden her site için ayrı kayıt açarsınız; her sitenin kendi data-website-id değeri olur.

Varsayılan şifreyi unuttum veya değiştirmedim, ne yapmalıyım?

Varsayılan admin / umami bilgileri belgede herkese açık yazıyor. Panel internete açıksa hemen giriş yapıp şifreyi değiştirin ve 2FA'yı açın; şüphe varsa kullanıcı listesini ve eklenen siteleri gözden geçirin.

Yazılım ve hizmet adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen projeler veya şirketlerle ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Uptime Kuma ile site izleme · Gitea kurulumu · Portainer ile Docker yönetimi · n8n VPS kurulumu · Docker Compose rehberi · Çerez politikası ve çerez bandı · VPS güvenlik sertleştirme