Matomo is a powerful, open-source web analytics platform designed for self-hosting. It provides complete control over your data, advanced customization, and privacy-focused tracking, making it an excellent alternative to proprietary analytics solutions. In this guide, we’ll cover actionable steps to deploy, configure, and manage Matomo, ensuring a seamless experience whether you’re a developer, system administrator, or tech-savvy user. By the end, you’ll have a fully functional, self-hosted analytics platform tailored to your needs.
Installing Matomo
📦 Docker/Docker Compose Setup
Using Docker is one of the easiest ways to deploy Matomo. Below is a docker-compose.yml file tailored for Matomo with MySQL as the database backend:
version: '3.7'
services:
matomo:
image: matomo:latest
container_name: matomo
ports:
- "8080:80"
volumes:
- ./matomo:/var/www/html
depends_on:
- db
environment:
MATOMO_DATABASE_HOST: db
MATOMO_DATABASE_ADAPTER: mysqli
MATOMO_DATABASE_TABLES_PREFIX: matomo_
MATOMO_DATABASE_USERNAME: matomo
MATOMO_DATABASE_PASSWORD: matomo_password
MATOMO_DATABASE_DBNAME: matomo_db
db:
image: mariadb:latest
container_name: matomo_db
volumes:
- ./db:/var/lib/mysql
environment:
MYSQL_ROOT_PASSWORD: root_password
MYSQL_DATABASE: matomo_db
MYSQL_USER: matomo
MYSQL_PASSWORD: matomo_password
Deploy Matomo using the following commands:
docker-compose up -d
## Check that the containers are running
docker ps
## Access Matomo via http://<your-server-ip>:8080
🚀 Manual Installation
If you prefer to manually install Matomo on a Linux server, follow these steps:
- Install necessary dependencies:
sudo apt update
sudo apt install -y apache2 mysql-server php php-mysql php-cli php-gd php-xml unzip wget
- Download and extract the latest Matomo release:
wget https://builds.matomo.org/matomo.zip
unzip matomo.zip -d /var/www/
sudo chown -R www-data:www-data /var/www/matomo
sudo chmod -R 755 /var/www/matomo
- Configure Apache to serve Matomo:
sudo nano /etc/apache2/sites-available/matomo.conf
<VirtualHost *:80>
ServerName your-domain.com
DocumentRoot /var/www/matomo
<Directory /var/www/matomo>
AllowOverride All
Require all granted
</Directory>
</VirtualHost>
Enable the configuration and restart Apache:
sudo a2ensite matomo.conf
sudo a2enmod rewrite
sudo systemctl restart apache2
- Complete the installation via the web interface at
http://<your-server-ip>.
Configuring Nginx as a Reverse Proxy
🌐 Nginx Configuration
Below is a sample Nginx configuration for routing traffic to Matomo:
server {
listen 80;
server_name your-domain.com;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
Save this configuration to /etc/nginx/sites-available/matomo, then enable it:
sudo ln -s /etc/nginx/sites-available/matomo /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
🔒 SSL/TLS Setup
Secure Matomo with Let's Encrypt SSL certificates:
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com
Test the certificate renewal process:
sudo certbot renew --dry-run
Logging and Debugging Matomo
🗃️ Enabling Debug Logs
To enable debug-level logging in Matomo, edit the config/config.ini.php file:
sudo nano /var/www/matomo/config/config.ini.php
Add or modify the following lines:
[log]
log_writers[] = file
log_level = DEBUG
📄 Viewing Logs
For Docker installations, view logs using:
docker logs matomo
For manual installations, check the Matomo log file:
tail -f /var/www/matomo/tmp/logs/matomo.log
🛠️ Troubleshooting Common Issues
-
Database Connection Errors: Verify the database host, username, and password in
config.ini.php. -
Permission Denied: Ensure Matomo files are owned by the web server user (e.g.,
www-data).
Backup and Restore
🗂️ File-Based Backups
Backup Matomo’s configuration and critical files:
sudo tar -czvf matomo-backup.tar.gz /var/www/matomo
🔄 Database Backups
Export Matomo’s database:
mysqldump -u matomo -p matomo_db > matomo_db_backup.sql
Restore the database:
mysql -u matomo -p matomo_db < matomo_db_backup.sql
📅 Automated Backup Scripts
Set up a cron job for periodic backups:
crontab -e
Add the following line:
0 2 * * * /usr/bin/mysqldump -u matomo -p'matomo_password' matomo_db > /backups/matomo_db_$(date +\%F).sql
Updating and Upgrading Matomo
⬆️ Updating Docker Images
Pull the latest Matomo image and redeploy your containers:
docker-compose pull
docker-compose down
docker-compose up -d
🛠️ Manual Updates
For manual installations, download the latest version and replace the old files:
wget https://builds.matomo.org/matomo.zip
unzip -o matomo.zip -d /var/www/
sudo chown -R www-data:www-data /var/www/matomo
Run the updater via the web interface.
Leveraging Matomo’s Unique Features
🔧 Enabling APIs
Matomo’s API allows advanced integrations. Generate an API token from Matomo’s interface, then use it in scripts, for example, with curl:
curl -X GET "http://your-domain.com/index.php?module=API&method=SitesManager.getAllSites&format=JSON&token_auth=your_api_token"
🌟 Advanced Configurations
Enable geolocation for detailed visitor data:
- Install GeoIP2:
sudo apt install -y geoip-database geoipupdate
- Enable geolocation in Matomo under "Administration > Geolocation."
Wrapping Up
By following the steps in this guide, you’ve deployed, configured, and secured your self-hosted Matomo analytics platform. With full control over your data, advanced customization options, and robust features like APIs and geolocation, Matomo empowers you to gain detailed insights into your web traffic. Start leveraging the provided code examples and configurations to unlock Matomo’s full potential!
