# Umami analitik Docker Compose ve HTTPS ile nasıl kurulur

> Umami web analitiğini Docker Compose ve PostgreSQL ile sunucunuza kurun, varsayılan girişi değiştirin, Caddy ile HTTPS sunun, sitelerinizi ekleyip yedekleyin.

Zorluk: Başlangıç\
Denendiği sistemler: Ubuntu 24.04 LTS, Ubuntu 26.04 LTS, Debian 12, Debian 13

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.

> **Not**
>
> Umami 3 MySQL desteğini kaldırdı ve yalnızca PostgreSQL destekler. MySQL kullanan mevcut bir Umami 2 kurulumunu taşıyorsanız önce verileri Umami'nin MySQL'den PostgreSQL'e geçiş rehberiyle aktarın.

## Ön koşullar

- **Ubuntu 24.04 LTS**, **Ubuntu 26.04 LTS**, **Debian 12** veya **Debian 13** çalıştıran bir sunucu.
- `sudo` yetkisine ve SSH anahtarıyla girişe sahip, root olmayan bir kullanıcı. [Yeni bir Linux sunucusunu güvenli hale getirin](/guides/secure-a-new-linux-server) ve [SSH anahtarlarını ayarlayın](/guides/ssh-keys) rehberlerine bakın.
- Compose eklentisiyle birlikte Docker Engine: [Ubuntu'ya Docker kurulumu](/guides/install-docker-ubuntu) veya [Debian'a Docker kurulumu](/guides/install-docker-debian).
- [Caddy ile reverse proxy](/guides/caddy-reverse-proxy) rehberinde anlatıldığı gibi sunucuya kurulmuş Caddy.
- Sunucunuza yönlenen bir A kaydına (IPv6 kullanıyorsanız AAAA kaydına da) sahip `analytics.example.com` gibi bir alan adı.

Umami belgeleri en düşük veritabanı sürümü olarak PostgreSQL 12.14'ü belirtir; aşağıdaki Compose dosyası PostgreSQL 15'i bir konteynerde çalıştırır. Proje en düşük CPU veya bellek gereksinimi yayınlamaz; bu yüzden aşağıdaki değerler resmi ya da ölçülmüş rakamlar değil, temkinli bir başlangıç noktasıdır:

| Kaynak | En düşük (resmi) | Önerilen başlangıç |
|---|---|---|
| CPU | Yayınlanmıyor | 1 vCPU |
| Bellek | Yayınlanmıyor | 1 GB RAM |
| Disk | Yayınlanmıyor | 10 GB; yoğun ve uzun süre veri tutulan siteler için daha fazla |
| Veritabanı | PostgreSQL 12.14 veya üstü | Compose dosyasındaki PostgreSQL 15 |

## 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`:

```bash
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:

```bash
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:

```yaml
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:

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

> **İpucu**
>
> Ne zaman yükselteceğinizi kontrol etmek için `latest` yerine bir sürüm sabitleyin. Umami'nin GitHub konteyner kayıt sayfası `3.4.0` gibi düz sürüm etiketleri listeler; orada listelenen en yeni sürümü kullanın, örneğin `ghcr.io/umami-software/umami:3.4.0`.

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

```bash
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:

```bash
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:

```bash
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:

```caddyfile
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:

```bash
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](/guides/nginx-reverse-proxy-certbot)) ve Traefik ([Traefik](/guides/traefik-reverse-proxy)) 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:

```text
<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`.

> **Not**
>
> Bazı site oluşturucular ve etiket yöneticileri script etiketlerinden `data-` özniteliklerini siler. Umami belgeleri Google Tag Manager için script öğesini JavaScript ile oluşturan özel bir HTML etiketi kullanmayı anlatır.

## 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:

```yaml
      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:

```bash
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:

```bash
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:

> **Uyarı**
>
> Bu komutlar yedeği yüklemeden önce mevcut Umami veritabanını siler. Bu sunucudaki veriler önemliyse önce yeni bir döküm alın.

```bash
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ı](https://github.com/umami-software/umami/releases) okuyun ve bir veritabanı yedeği alın. Ardından Umami'nin Docker Compose için belgelediği güncelleme yöntemini izleyin:

```bash
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:

```bash
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](/guides/install-matomo).
- Başka bir hafif seçeneği deneyin: [Plausible Community Edition](/guides/install-plausible-ce).
- Aynı proxy arkasında başka uygulamalar barındırmak için [Caddy ile reverse proxy](/guides/caddy-reverse-proxy) rehberini kullanın.
- Kendi sunucunuzda analitik için sunucuları [web analitiği hosting](/web-analytics-hosting) sayfasında inceleyin.
- Olayları, raporları ve API'yi [Umami belgelerinde](https://docs.umami.is/docs) keşfedin.

## Sık sorulan sorular

### Umami hâlâ MySQL destekliyor mu?

Hayır. Umami 3 yalnızca PostgreSQL destekler. Umami 2'yi MySQL üzerinde çalıştırıyorsanız 3. sürüme yükseltmeden önce Umami'nin MySQL'den PostgreSQL'e geçiş rehberini izleyin.

### Umami'nin varsayılan girişi nedir?

Yeni bir kurulum admin kullanıcısını umami parolasıyla oluşturur. İlk girişten hemen sonra Settings, Profile, Change password yolundan parolayı değiştirin. Bu rehber bunu site herkese açılmadan önce bir SSH tüneli üzerinden yapar.

### Bazı ziyaretler Umami'de neden görünmüyor?

Reklam engelleyiciler ve gizlilik eklentileri analitik betiklerini çoğu zaman adına veya yoluna göre engeller. Umami, kendi sunucunuzda izleme betiğini TRACKER_SCRIPT_NAME ile, veri toplama uç noktasını COLLECT_API_ENDPOINT ile yeniden adlandırmanıza izin verir; bu etkiyi azaltır ama tamamen ortadan kaldırmaz.

### Neleri yedeklemeliyim?

Web siteleri, kullanıcılar ve toplanan olaylar dahil tüm Umami verileri PostgreSQL'de durur. Veritabanını pg_dump ile yedekleyin; Compose dosyasını ve gizli değerlerinizi içeren .env dosyasını da saklayın.

### Umami hangi HyperDC sunucularında çalışır?

Umami, root erişiminiz ve desteklenen bir Ubuntu veya Debian sürümünüz olan her HyperDC Linux VPS, VDS veya dedicated sunucuda Docker içinde çalışır. Tek bir sunucu birçok web sitesinin analitiğini barındırabilir.

---

Kaynak: <https://hyperdc.com/tr/guides/tutorials/install-umami>\
Son güncelleme: 2026-10-09