Installing Matomo (Pi

Configuration

After installing all components, they need to be configured correctly for Matomo to function properly and securely.

1. Nginx Configuration for Matomo

Let's create a new Nginx configuration file for your domain. Replace your_domain.com with your actual domain.

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

Insert the following configuration block. This configures Nginx to serve Matomo, using PHP-FPM and providing basic security. Pay attention to fastcgi_pass unix:/run/php/php8.3-fpm.sock; – this is the path to the PHP-FPM socket.

server {
    listen 80;
    server_name your_domain.com www.your_domain.com;
    root /var/www/matomo;
    index index.php index.html index.htm;

    # Ensure Matomo can be accessed via HTTPS
    # This block will be updated by Certbot for HTTPS
    location / {
        try_files $uri /index.php$is_args$args;
    }

    # Block access to sensitive Matomo files
    location ~ /(config|tmp|core|vendor)/ {
        deny all;
        return 404;
    }
    location ~ /\. {
        deny all;
        return 404;
    }
    location ~ \.ini$ {
        deny all;
        return 404;
    }

    # PHP-FPM configuration
    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
        fastcgi_index index.php;
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_buffer_size 128k;
        fastcgi_buffers 4 256k;
        fastcgi_busy_buffers_size 256k;
        fastcgi_temp_file_write_size 256k;
    }

    # Static file caching configuration
    location ~ \.(js|css|png|jpg|jpeg|gif|ico|svg|webp)$ {
        expires 365d;
        add_header Cache-Control "public, no-transform";
    }

    # Additional security headers
    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-XSS-Protection "1; mode=block";
    add_header X-Content-Type-Options "nosniff";
    add_header Referrer-Policy "no-referrer-when-downgrade";
}

Save the file, create a symbolic link, and test the Nginx configuration:

sudo ln -s /etc/nginx/sites-available/matomo.conf /etc/nginx/sites-enabled/
sudo nginx -t                          # Test config syntax
sudo systemctl reload nginx            # Reload Nginx

If the test is successful, Nginx should be ready.

2. PHP-FPM Configuration

For Matomo, it is recommended to increase some PHP limits. Open the php.ini file for PHP-FPM:

sudo nano /etc/php/8.3/fpm/php.ini

Find and modify the following parameters:

memory_limit = 512M               ; Minimum 256M, 512M is better for large installations
max_execution_time = 300          ; Increase for long archiving operations
post_max_size = 64M
upload_max_filesize = 64M
date.timezone = Europe/Berlin     ; Set your timezone, e.g., "Europe/Moscow"

Save changes and restart PHP-FPM:

sudo systemctl restart php8.3-fpm

3. SSL/TLS Installation with Certbot

Using HTTPS is absolutely essential for any web analytics. Let's install Certbot for automatic issuance and renewal of Let's Encrypt SSL certificates.

sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d your_domain.com -d www.your_domain.com

Follow the Certbot instructions. It will ask for your email for notifications and agreement to the terms of service. After successful certificate issuance, Certbot will automatically update your Nginx config to redirect HTTP to HTTPS and use the new certificate. It will also configure automatic certificate renewal.

Check that automatic renewal is working:

sudo certbot renew --dry-run

If you see the message The dry run was successful, then everything is configured correctly.

4. Completing Matomo Installation via Web Interface

Now that the entire stack is configured, open your domain (https://your_domain.com) in a web browser. You will see the Matomo welcome page.

1. Welcome: Click "Next".
2. System Check: Matomo will check all system requirements. Ensure all items are marked green. If there are warnings, revisit PHP settings or access permissions.
3. Database Setup: Enter the details you created earlier:
   • Database Server: 127.0.0.1 or localhost
   • Login: matomo_user
   • Password: your_strong_password
   • Database Name: matomo_db
   • Table prefix: matomo_ (can be left as default)
   • Adapter: PDO\MYSQL
   Click "Next". Matomo will create all necessary tables.
4. Super User: Create a Matomo super user account. This is the main administrator account. Remember the login and password.
5. Website Setup: Enter information about your first website to track (URL, timezone, etc.).
6. JavaScript Tracking Code: Matomo will provide you with JavaScript code to embed on your website. Copy it and paste it before the closing </body> tag on all pages you want to track.

After this, you will be redirected to the Matomo dashboard.

5. Configuring Cron Jobs for Matomo

Matomo uses cron jobs for archiving reports. This is critically important for performance, as without it, Matomo will process reports in real-time, which will slow down the interface. Open crontab for the www-data user:

sudo -u www-data crontab -e

If this is the first time, choose an editor (e.g., nano). Add the following lines to the end of the file:

# Matomo archive processing
5     /usr/bin/php8.3 /var/www/matomo/console core:archive --url=https://your_domain.com/ > /var/www/matomo/tmp/logs/matomo-archive.log 2>&1

This command will run Matomo archiving every hour at 5 minutes past the hour, saving the output to a log file. Replace your_domain.com with your domain. Ensure the path to php8.3 is correct (you can find it using which php8.3).

6. Verifying Functionality

Ensure Matomo is accessible and working:

• Open https://your_domain.com in your browser. You should see the Matomo login panel.
• Try logging in with the super user account.
• Check Nginx logs: sudo tail -f /var/log/nginx/access.log and sudo tail -f /var/log/nginx/error.log.
• Check PHP-FPM logs: sudo tail -f /var/log/php8.3-fpm.log (path may vary).
• Check Matomo archiving logs: sudo tail -f /var/www/matomo/tmp/logs/matomo-archive.log.

If you see traffic on your website, data will start appearing in Matomo after some time.

Troubleshooting + FAQ

In this section, we will cover common issues you might encounter during Matomo installation and operation, and provide answers to frequently asked questions.

Matomo does not load or returns a 500/502 error

What to check: This is a common issue indicating problems with PHP-FPM or Nginx operation.

1. Nginx Logs: Check /var/log/nginx/error.log for errors related to fastcgi_pass or access permissions.
2. PHP-FPM Logs: Check /var/log/php8.3-fpm.log (or similar path) for PHP errors.
3. PHP-FPM Status: Ensure PHP-FPM is running: sudo systemctl status php8.3-fpm.
4. Nginx Status: Ensure Nginx is running: sudo systemctl status nginx.
5. Permissions: Ensure the www-data user has full permissions for the Matomo directory: sudo ls -la /var/www/matomo.

How to fix: Restart Nginx and PHP-FPM. If it's a 502 error, increasing fastcgi_buffers in the Nginx config or memory_limit in php.ini often helps. Verify that the PHP-FPM socket path in the Nginx config (fastcgi_pass unix:/run/php/php8.3-fpm.sock;) matches the actual path.

Slow loading of Matomo pages or reports

What to check: Slow performance can be caused by several factors.

1. Cron Jobs: Ensure that Matomo archiving cron jobs are configured and running. If archiving is not happening, Matomo will generate reports in real-time, which is very resource-intensive. Check sudo -u www-data crontab -l and the archiving logs.
2. Opcache: Verify that PHP Opcache is enabled and correctly configured. Increase opcache.memory_consumption in php.ini if necessary.
3. Server Resources: Use htop or top to monitor CPU and RAM usage during report loading. If CPU or RAM is consistently at 100%, your VPS might not be powerful enough.
4. MySQL Settings: For very large databases, MySQL optimization may be required (e.g., indexing, configuring innodb_buffer_pool_size).

How to fix: Configure cron jobs. Increase PHP memory_limit and Opcache parameters. If server resources are insufficient, consider upgrading to a more powerful VPS. For MySQL, consult a DBA or use optimization tools.

Data is not being collected, although the tracking code is installed

What to check: This means Matomo is not receiving information from your website.

1. Tracking Code: Ensure that the Matomo JavaScript code is correctly embedded on all pages of your website, and that the domain in the code matches the Matomo domain.
2. Network Requests: Open the browser's developer console (F12) and go to the "Network" tab. Check if your website is sending requests to Matomo (usually to matomo.php). There should be a request with a 200 OK status.
3. Nginx Logs: Check Nginx's access.log for requests to matomo.php.
4. Firewall: Ensure your firewall (UFW) is not blocking incoming connections on port 80/443.
5. Trusted Hosts: In Matomo's config/config.ini.php, check the [General] section and the trusted_hosts[] parameter. Ensure your Matomo domain is listed there.

How to fix: Correct the tracking code. Check firewall settings. Add your domain to trusted_hosts[] in Matomo. Restart Nginx.

How to update Matomo safely?

Answer: A safe Matomo update always begins with a full backup of the database and files. Then, you can use the built-in update mechanism via the web interface (if available) or the command line. For CLI updates, navigate to the Matomo directory and execute the command sudo -u www-data php console core:update. This method is preferred for production servers as it is more controlled and helps avoid browser timeouts. After updating, always check logs for errors.

What is the minimum VPS configuration suitable for Matomo?

Answer: For small websites (up to 10,000 visits per day), a minimum VPS with 2 CPU cores, 4 GB of RAM, and 100 GB NVMe SSD will be required. An NVMe disk is critical for Matomo database performance. The network should be at least 200 Mbps. This will be sufficient for stable Matomo operation and comfortable report loading.

What to choose — VPS or dedicated for Matomo?

Answer: The choice between a VPS and a dedicated server depends on the scale of your project. For most small to medium-sized websites (up to 100,000 - 200,000 visits per day), a powerful VPS will be an optimal solution, offering a good balance between performance and cost. A dedicated server becomes necessary for very high loads (hundreds of thousands or millions of visits), when maximum performance, full control over hardware (e.g., for specific RAID arrays), or strict resource isolation requirements are needed. If you are just starting, always choose a VPS and scale up as your needs grow.

How to protect Matomo from spam and incorrect data?

Answer: Matomo has built-in features for spam protection. In the website settings, you can enable filtering by IP addresses or ranges, and exclude specific URLs or parameters from tracking. It is also recommended to use the "Bots & Spiders" functionality to automatically exclude known search bots. For more advanced protection, you can use additional Matomo plugins or configure Nginx rules to block suspicious requests to matomo.php.