Matomo Ubuntu veya Debian'a Nginx ve MariaDB ile nasıl kurulur

Matomo, kendi sunucunuzda çalıştırdığınız açık kaynaklı bir web analitiği platformudur; ziyaretçi verileri üçüncü taraf bir servis yerine kendi veritabanınızda kalır. Ticari analitik araçlarına benzer raporlar sunar; ayrıca IP anonimleştirme, takipten çıkma (opt-out) ve onay tabanlı izleme gibi gizlilik denetimleri içerir.

Bu rehber Matomo On-Premise'i, Matomo'nun kurulum rehberinde anlatılan klasik yöntemle kurar: Matomo'nun yayınladığı yapılandırmayla Nginx, dağıtımınızdan PHP-FPM ve MariaDB, resmi matomo.zip sürümü ve Certbot ile alınan bir Let's Encrypt sertifikası. Ardından rapor işlemeyi bir cron görevine taşır, coğrafi konum ve gizlilik seçeneklerini ayarlar, Matomo'yu nasıl yedekleyeceğinizi, geri yükleyeceğinizi ve güncelleyeceğinizi öğrenirsiniz. Bu rehber yazılırken güncel sürüm Matomo 5.14.1'dir; Matomo 6.0.0 beta aşamasındadır.

Adım 1 — Nginx, PHP-FPM ve MariaDB'yi kurun

Web sunucusunu, veritabanını, PHP-FPM'i ve Matomo'nun gerektirdiği veya önerdiği PHP eklentilerini (pdo_mysql veya mysqli, ayrıca curl, gd, xml, mbstring, intl ve zip) kurun:

sudo apt update
sudo apt install nginx mariadb-server php-fpm php-cli php-mysql php-curl php-gd php-xml php-mbstring php-intl php-zip unzip curl

php üst paketi yerine php-fpm kurmak Apache'nin sunucuya gelmesini önler. Sürümleri kontrol edin ve PHP sürümünü içeren PHP-FPM soket adını bulun:

php -v
systemctl status nginx mariadb --no-pager
ls /run/php/

php -v PHP 8 göstermeli, /run/php/ içinde de php8.3-fpm.sock gibi bir soket bulunmalıdır. Sürüm numarası Ubuntu ve Debian sürümleri arasında farklıdır; bu değeri Adım 5'te kullanacaksınız.

Adım 2 — Veritabanını ve kullanıcıyı oluşturun

Matomo, yalnızca kendi veritabanına erişebilen bir kullanıcıyla ayrı bir veritabanı önerir. Önce güçlü bir parola üretin ve web kurulum sihirbazı için saklayın:

openssl rand -hex 24
sudo mariadb

Ubuntu ve Debian'da sudo mariadb sizi yerel soket üzerinden veritabanı root kullanıcısı olarak bağlar. Aşağıdaki komutları çalıştırın ve change-me yerine ürettiğiniz parolayı yazın:

CREATE DATABASE matomo;
CREATE USER 'matomo'@'localhost' IDENTIFIED BY 'change-me';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, INDEX, DROP, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES ON matomo.* TO 'matomo'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Bunlar Matomo'nun veritabanı SSS sayfasında listelenen yetkilerdir. Matomo, LOAD DATA INFILE ile arşivlemeyi hızlandıran isteğe bağlı genel bir FILE yetkisinden de söz eder; bu rehber veritabanı kullanıcısını kendi veritabanıyla sınırlı tutmak için bu yetkiyi vermez.

Adım 3 — Matomo'yu indirin

Resmi sürümü builds.matomo.org adresinden indirin, açın ve /var/www/matomo konumuna taşıyın. Matomo üçüncü taraf indirme kaynaklarını kullanmamanızı ister; arşivi doğrulamak isterseniz GPG imzaları da yayınlar:

cd /tmp
curl -fLO https://builds.matomo.org/matomo.zip
unzip -q matomo.zip
sudo mv /tmp/matomo /var/www/matomo
sudo chown -R www-data:www-data /var/www/matomo
ls /var/www/matomo

config, core, plugins ve tmp gibi klasörleri ve console betiğini görmelisiniz. Klasörün tamamının sahibini www-data yapmak Matomo'nun tmp/ ve config/ içine yazmasını, coğrafi konum veritabanlarını misc/ içine indirmesini ve tek tıkla güncelleme aracını kullanmasını sağlar.

Adım 4 — Güvenlik duvarını açın ve sertifika alın

SSH ve web trafiğine izin verin, ardından Certbot'u Nginx eklentisiyle kurun:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo apt install certbot python3-certbot-nginx

Burada dağıtımınızın Certbot paketleri kullanılır; bunlar bir yenileme zamanlayıcısı içerir. Certbot ekibi bunun yerine snap paketini önerir; Nginx reverse proxy ve Certbot rehberi bu yöntemi gösterir. İkisi de çalışır, ancak yalnızca birini kurun.

Matomo alan adınız için sertifika isteyin. certonly sertifikayı Nginx dosyalarınızı değiştirmeden alır; deploy hook ise her yenilemeden sonra Nginx'i yeniden yükleyerek yeni sertifikanın kullanılmasını sağlar:

sudo certbot certonly --nginx -d matomo.example.com --deploy-hook "systemctl reload nginx"
sudo ls /etc/letsencrypt/live/matomo.example.com/
sudo certbot renew --dry-run

fullchain.pem ve privkey.pem dosyalarını görmelisiniz; deneme çalıştırması da yenilemenin başarılı olacağını bildirmelidir. Certbot hakkında daha fazla bilgi için Nginx ve Certbot rehberine bakın.

Adım 5 — Nginx'i Matomo'nun yapılandırmasıyla ayarlayın

Matomo, matomo-nginx deposunda bir Nginx yapılandırması yayınlar. Bu yapılandırma PHP'ye yalnızca Matomo'nun giriş betiklerini iletir, diğer tüm PHP dosyaları için 403 döndürür ve config, tmp, core, lang, libs, vendor, plugins ile misc klasörlerini engeller.

Önce TLS ayarları parçasını oluşturun. Bu dosya Matomo'nun ssl.conf dosyasındaki oturum ve şifre takımı değerlerini kullanır, TLS 1.3 ekler ve OCSP stapling'i dışarıda bırakır; çünkü Let's Encrypt OCSP sunucularını Ağustos 2025'te kapattı:

sudo nano /etc/nginx/snippets/matomo-ssl.conf

ssl_session_timeout 1d;
ssl_session_cache shared:SSL:50m;
ssl_session_tickets off;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers 'ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256';
ssl_prefer_server_ciphers on;

Ardından site dosyasını oluşturun:

sudo nano /etc/nginx/sites-available/matomo.conf

Matomo'nun yapılandırmasını alan adınız, sertifika yolları, TLS parçası ve kurulum yolu doldurulmuş haliyle yapıştırın:

server {
    listen [::]:80;
    listen 80;
    server_name matomo.example.com;
    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen [::]:443 ssl http2;
    listen 443 ssl http2;
    server_name matomo.example.com;
    access_log /var/log/nginx/matomo.access.log;
    error_log /var/log/nginx/matomo.error.log;

    ssl_certificate /etc/letsencrypt/live/matomo.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/matomo.example.com/privkey.pem;
    include snippets/matomo-ssl.conf;

    add_header Referrer-Policy origin always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;

    root /var/www/matomo/;
    index index.php;

    location ~ ^/(index|matomo|piwik|js/index|plugins/HeatmapSessionRecording/configs)\.php$ {
        include snippets/fastcgi-php.conf;
        try_files $fastcgi_script_name =404;
        fastcgi_param HTTP_PROXY "";
        fastcgi_pass unix:/run/php/php-fpm.sock;
    }

    location ~* ^.+\.php$ {
        deny all;
        return 403;
    }

    location / {
        try_files $uri $uri/ =404;
    }

    location ~ ^/(config|tmp|core|lang) {
        deny all;
        return 403;
    }

    location ~ /\.ht {
        deny all;
        return 403;
    }

    location ~ js/container_.*_preview\.js$ {
        expires off;
        add_header Cache-Control 'private, no-cache, no-store';
    }

    location ~ \.(gif|ico|jpg|png|svg|js|css|htm|html|mp3|mp4|wav|ogg|avi|ttf|eot|woff|woff2)$ {
        allow all;
        expires 1h;
        add_header Pragma public;
        add_header Cache-Control "public";
    }

    location ~ ^/(libs|vendor|plugins|misc|node_modules) {
        deny all;
        return 403;
    }

    location ~/(.*\.md|LEGALNOTICE|LICENSE) {
        default_type text/plain;
    }
}

fastcgi_pass satırını Adım 1'de gördüğünüz sürümlü PHP-FPM soketine yönlendirin, siteyi etkinleştirin, yapılandırmayı test edin ve Nginx'i yeniden yükleyin:

PHPV=$(php -r 'echo PHP_MAJOR_VERSION.".".PHP_MINOR_VERSION;')
sudo sed -i "s#/run/php/php-fpm.sock#/run/php/php${PHPV}-fpm.sock#" /etc/nginx/sites-available/matomo.conf
grep fastcgi_pass /etc/nginx/sites-available/matomo.conf
sudo ln -s /etc/nginx/sites-available/matomo.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
curl -I https://matomo.example.com/

nginx -t çıktısı "test is successful" ile bitmeli, curl da kurulum sayfası için HTTP/2 200 döndürmelidir.

Adım 6 — Web kurulum sihirbazını çalıştırın

https://matomo.example.com/ adresini hemen tarayıcınızda açın: kurulum tamamlanana kadar bu adrese ulaşan herkes kurulumu bitirebilir. Ekranları izleyin:

1. Welcome ve System check: hata olarak işaretlenen her şeyi düzeltin ve devam edin.
2. Database setup: veritabanı sunucusu localhost (PHP yerel soket üzerinden bağlanır ve 'matomo'@'localhost' hesabıyla eşleşir), kullanıcı matomo, Adım 2'deki parola, veritabanı adı matomo. Varsayılan tablo önekini ve bağdaştırıcıyı koruyun.
3. Superuser: benzersiz bir kullanıcı adı ve uzun bir parolayla tek Süper Kullanıcıyı oluşturun.
4. First website: izlemek istediğiniz sitenin adını ve adresini girin.
5. Tracking code: JavaScript kodunu kopyalayın ve sitenizin her sayfasına, tercihen kapanış head etiketinin hemen öncesine veya ortak bir başlık şablonuna ekleyin.

Continue to Matomo düğmesine tıklayın ve giriş yapın. Şimdi HTTPS'yi Matomo'nun kendisinde de zorunlu kılın. Kurulum sihirbazının yazdığı yapılandırma dosyasını açın:

sudo nano /var/www/matomo/config/config.ini.php

Mevcut [General] bölümünü bulun ve bu iki satırı, orada zaten bulunan satırların altına, bölümün içine ekleyin:

force_ssl = 1
browser_archiving_disabled_enforce = 1

force_ssl her Matomo isteğini HTTPS'ye yönlendirir. browser_archiving_disabled_enforce raporların biri onları görüntülediğinde işlenmesini durdurur; bu işi bir sonraki adımdaki cron görevi üstlenir. Son olarak Administration → Personal → Security altında hesabınız için iki aşamalı doğrulamayı açın ve kurtarma kodlarını güvenli bir yerde saklayın.

Matomo; e-posta raporlarını, kullanıcı davetlerini ve parola sıfırlama bağlantılarını Administration → System → General settings altındaki Email server settings bölümünde ayarladığınız SMTP sunucusu üzerinden gönderir (örneğin smtp.example.com sunucusu, 587 numaralı port ve STARTTLS); ayarı sudo -u www-data php /var/www/matomo/console core:test-email [email protected] ile test edin.

Adım 7 — Raporları cron ile işleyin

Administration → System → General settings bölümünde Archive reports when viewed from the browser değerini No, Archive reports at most every X seconds değerini 3600 yapın ve kaydedin. Web kök dizininin dışında bir log klasörü oluşturun ve arşivleyiciyi web sunucusu kullanıcısıyla test edin:

sudo install -d -o www-data -g www-data -m 750 /var/log/matomo
sudo -u www-data /usr/bin/php /var/www/matomo/console core:archive --matomo-domain=https://matomo.example.com

Başarılı bir çalıştırma, hata olmadığını bildiren bir özetle biter. --matomo-domain, Matomo'nun 5. sürümde kullanımdan kaldırdığı eski --url seçeneğinin yerini alır. Şimdi arşivleyiciyi Matomo'nun önerdiği gibi her saatin beşinci dakikasında çalışacak şekilde zamanlayın:

sudo nano /etc/cron.d/matomo-archive

5 * * * * www-data /usr/bin/php /var/www/matomo/console core:archive --matomo-domain=https://matomo.example.com > /var/log/matomo/archive.log 2>&1

Altıncı alan görevi www-data olarak çalıştırır; böylece oluşturduğu dosyalar Matomo'nun geri kalanıyla aynı sahibe sahip olur. Bir sonraki tam saatten sonra /var/log/matomo/archive.log dosyasını kontrol edin. Bir çalıştırma bir saatten uzun sürerse Matomo görevi daha seyrek, örneğin 2, 6 veya 12 saatte bir çalıştırmayı önerir.

Adım 8 — Coğrafi konumu ayarlayın

Matomo her ziyaretçinin ülkesini, bölgesini ve şehrini kendi sunucunuzda saklanan bir coğrafi konum veritabanında arar; bu nedenle IP adresleri bu iş için dış bir servise gönderilmez. Administration → System → Geolocation bölümüne gidin:

1. Sayfanın altındaki Setup automatic updates of GeoIP databases bölümünde Matomo'nun ücretsiz DB-IP şehir veritabanını indirmesine izin verin veya bir MaxMind hesabınız varsa MaxMind GeoIP2 veritabanının indirme adresini girin.
2. Haftalık veya aylık bir güncelleme sıklığı seçin. Güncellemeler Adım 7'deki arşivleme cron görevinin parçası olarak çalışır.
3. DBIP / GeoIP 2 (Php) sağlayıcısını seçin ve kaydedin. Sağlayıcı Installed olarak görünmelidir.

Veritabanı /var/www/matomo/misc/ içinde saklanır; bu klasörün www-data tarafından yazılabilir olması bu yüzden gereklidir. Yeni ziyaretlerin konumu bundan sonra belirlenir; önceki ziyaretler izlendikleri anda aldıkları konumu korur.

Adım 9 — Gizlilik ayarlarını gözden geçirin

Matomo Administration → Privacy altında birkaç gizlilik denetimi sunar. Hangilerine ihtiyacınız olduğu sitelerinize uygulanan kurallara bağlıdır; bu rehber yalnızca her birinin ne yaptığını anlatır.

• Anonymize data: Anonymize Visitors' IP addresses seçeneğini açın ve kaç baytın maskeleneceğini seçin (1, 2 veya 3 ya da tam maskeleme). Coğrafi konumun maskelenmiş adresi (daha yüksek gizlilik, daha düşük doğruluk) mi yoksa tam adresi mi kullanacağına da siz karar verirsiniz. Aynı sayfa User ID değerlerini takma adla değiştirebilir ve toplu raporları korurken Regularly delete old raw data ile eski ham verileri silebilir.
• Users opt-out: takipten çıkma formunun kodunu gizlilik sayfanıza kopyalayın. Takipten çıkan ziyaretçiler mtm_consent_removed çerezini alır ve artık izlenmez. Matomo, Support Do Not Track preference seçeneğini kullanımdan kaldırılmış olarak işaretler.
• Onay: siteniz onay istiyorsa izleme kodunun en üstüne, trackPageView satırından önce _paq.push(['requireConsent']); (onay verilene kadar izleme yok) veya _paq.push(['requireCookieConsent']); (onay verilene kadar çerezsiz izleme) ekleyin ve onay bannerınızdan ilgili setConsentGiven veya rememberConsentGiven fonksiyonlarını çağırın. Hiç çerez kullanmadan izlemek için trackPageView satırından önce _paq.push(['disableCookies']); ekleyin.
• GDPR Overview ve GDPR Tools: tek bir ziyaretçinin verilerini bulun, dışa aktarın veya silin.

Yedekleme ve geri yükleme

Tam bir Matomo yedeği iki parçadan oluşur: tüm izleme verilerini ve raporları tutan MariaDB veritabanı ve Matomo klasörü; özellikle veritabanı girişini, salt değerini ve etkin eklentilerin listesini içeren config/config.ini.php. Matomo'nun yedekleme SSS sayfası mysqldump aracını bu seçeneklerle kullanır; MariaDB'de aynı aracın adı mariadb-dump şeklindedir:

sudo mkdir -p /opt/backups && sudo chown $USER:$USER /opt/backups && chmod 700 /opt/backups
sudo mariadb-dump --extended-insert --no-autocommit --quick --single-transaction matomo | gzip > /opt/backups/matomo-db-$(date +%F).sql.gz
sudo tar czf /opt/backups/matomo-files-$(date +%F).tar.gz --exclude=matomo/tmp -C /var/www matomo
ls -lh /opt/backups

Döküm ziyaretçi verileri içerir; gizli tutun ve sunucunun dışına kopyalayın. Yaklaşık 10 GB'tan büyük veritabanlarında veya ayda bir milyonun üzerinde eylemde Matomo döküm yerine Percona XtraBackup kullanmayı önerir.

Yeni bir sunucuya geri yüklemek için Adım 1–5'i (paketler, veritabanı ve kullanıcı, sertifika ve Nginx) tekrarlayın; ancak yeni bir matomo.zip indirmek yerine dosya yedeğinizi açın. Ardından veritabanı dökümünü içe aktarın:

sudo tar xzf /opt/backups/matomo-files-2026-10-09.tar.gz -C /var/www
sudo install -d -o www-data -g www-data /var/www/matomo/tmp
sudo chown -R www-data:www-data /var/www/matomo
gunzip -c /opt/backups/matomo-db-2026-10-09.sql.gz | sudo mariadb matomo

Geri yüklenen config.ini.php dosyasındaki veritabanı adını, kullanıcıyı ve parolayı kullanın, /etc/cron.d/matomo-archive dosyasını yeniden oluşturun ve raporlarınızın geri geldiğini görmek için Matomo'yu açın.

Matomo güncelleme

Her güncellemeden önce değişiklik günlüğünü okuyun ve veritabanını ile config/config.ini.php dosyasını yedekleyin. Yeni bir sürüm çıktığında Matomo, Süper Kullanıcılara Administration sayfasında bir bildirim gösterir; Adım 3'teki sahiplik ayarıyla bu güncellemeyi tek tıkla güncelleme düğmesiyle uygulayabilirsiniz.

Matomo'nun yoğun sunucular için önerdiği komut satırı yöntemini kullanmak isterseniz yeni sürümü indirin, mevcut dosyaların üzerine kopyalayın ve veritabanı yükseltmesini çalıştırın. Arşiv config/config.ini.php dosyasını içermez; bu yüzden yapılandırmanız korunur:

cd /tmp
rm -rf /tmp/matomo /tmp/matomo.zip
curl -fLO https://builds.matomo.org/matomo.zip
unzip -q matomo.zip
sudo cp -a /tmp/matomo/. /var/www/matomo/
sudo chown -R www-data:www-data /var/www/matomo
sudo -u www-data php /var/www/matomo/console core:update
sudo -u www-data php /var/www/matomo/console diagnostics:unexpected-files

Son komut eski sürümlerden kalan dosyaları listeler; listeyi inceledikten sonra bunları diagnostics:unexpected-files --delete ile silin. Ardından Administration → Diagnostics → System check sayfasını açın ve önerilerini uygulayın. İşletim sistemi paketlerini de sudo apt update && sudo apt upgrade ile güncel tutun.

Matomo 6, PHP 8.1 veya üstü ile MySQL 8.0 ya da MariaDB 10.6 veya üstünü gerektirir. Bu sürüme geçmeden önce php -v ve mariadb --version çıktılarını kontrol edin ve sürüm notlarını okuyun.

Sorun giderme

502 Bad Gateway

Nginx PHP-FPM'e ulaşamıyor. grep fastcgi_pass /etc/nginx/sites-available/matomo.conf çıktısındaki soketi ls /run/php/ çıktısındaki dosyayla karşılaştırın, yolu düzeltin ve sudo nginx -t && sudo systemctl reload nginx komutunu çalıştırın. PHP-FPM'in çalıştığını systemctl status 'php*-fpm' --no-pager ile kontrol edin.

nginx -t sertifikayı yükleyemediğini bildiriyor

Alan adı için sertifika henüz alınmamış veya dosyadaki alan adı sertifikayla eşleşmiyor. Mevcut sertifikaları sudo certbot certificates ile listeleyin, doğrulama başarısız olduysa DNS kaydını düzeltin ve Nginx'i yeniden yüklemeden önce Adım 4'ü tekrarlayın.

Sistem kontrolü tmp/ veya config/ klasörünün yazılabilir olmadığını söylüyor

Dosyaların sahibi PHP-FPM kullanıcısı değil. sudo chown -R www-data:www-data /var/www/matomo komutunu çalıştırın ve sayfayı yenileyin. Adım 3'teki ipucundaki sıkı izinleri seçtiyseniz tmp/ ve config/config.ini.php dosyalarının hâlâ yazılabilir olduğundan emin olun.

Raporlar boş kalıyor veya günde yalnızca bir kez güncelleniyor

Tarayıcı ile arşivleme kapalı ama cron görevi çalışmıyor. /var/log/matomo/archive.log dosyasını ve grep CRON /var/log/syslog çıktısını (Debian'da journalctl -u cron) kontrol edin; hatayı görmek için Adım 7'deki komutu www-data olarak elle çalıştırın. /etc/cron.d/matomo-archive dosyasının yeni satırla bittiğinden emin olun.

Matomo güvenilmeyen bir sunucu adından erişildiği uyarısı veriyor

Matomo yalnızca tanıdığı sunucu adlarını kabul eder. Matomo'ya yeni bir adla erişiyorsanız config/config.ini.php dosyasının [General] bölümüne trusted_hosts[] = "matomo.example.com" gibi bir satır ekleyin.

Sonraki adımlar

• Daha hafif, çerezsiz bir alternatifi karşılaştırın: Umami nasıl kurulur veya Plausible Community Edition.
• Certbot ve Nginx hakkında daha fazlasını Nginx ve Certbot rehberinde öğrenin.
• Kendi barındırdığınız bir WordPress sitesini izleyin: LEMP yığınında WordPress.
• Kendi sunucunuzda analitik için sunucuları web analitiği hosting sayfasında inceleyin.
• Kurulumu Matomo'nun güvenlik önerileriyle daha da sıkılaştırın.