Matomo Deployment and Usage Guide

1. Prerequisites

Before installing Matomo, ensure your server meets these requirements:

System Requirements:

PHP 7.2.5 or greater
MySQL 5.5+ or MariaDB
PHP extensions: pdo and pdo_mysql, or the mysqli extension
Web server (Apache, Nginx, or IIS)
Minimum 128MB PHP memory limit (256MB recommended)

Optional but Recommended:

PHP extensions: gd, xml, curl, json
mod_rewrite for Apache (for pretty URLs)
SSL certificate for HTTPS

For Development:

Git
Composer
DDEV (for local development environment)

2. Installation

Method A: Direct Download (Recommended for Production)

Download the latest release:

wget https://builds.matomo.org/matomo.zip
# or
curl -O https://builds.matomo.org/matomo.zip

Extract and upload to your web server:

unzip matomo.zip
mv matomo /var/www/html/matomo/

Set proper permissions:

chown -R www-data:www-data /var/www/html/matomo/
chmod -R 755 /var/www/html/matomo/tmp/

Method B: Git Clone (For Development)

Clone the repository:

git clone https://github.com/matomo-org/matomo.git
cd matomo

Initialize the DDEV environment:
```
ddev start
ddev composer install
```
Access the installation wizard at http://matomo.ddev.site

Web Installation Wizard

Point your browser to the Matomo directory (e.g., https://yourdomain.com/matomo/)
Follow the 5-step installation process:
- System check
- Database setup
- Super user creation
- Website configuration
- JavaScript tracking code generation
Copy the generated JavaScript tracking code and add it to all pages you want to track.

3. Configuration

Database Configuration

During installation, you'll need:

Database host (usually localhost)
Database name
Database username and password
Table prefix (optional)

Post-Installation Configuration Files

Primary configuration file: config/config.ini.php

[database]
host = "localhost"
username = "matomo_user"
password = "your_password"
dbname = "matomo_db"
tables_prefix = "matomo_"

Environment-specific settings:

config/config.ini.php - Main configuration (auto-generated)
config/common.config.ini.php - Shared settings across environments
config/environment/config.ini.php - Environment-specific overrides

Important Security Settings

Protect your config file:

chmod 644 config/config.ini.php
chown www-data:www-data config/config.ini.php

Enable HTTPS in General Config:

[General]
force_ssl = 1
assume_secure_protocol = 1

Configure Privacy Settings (in Administration → Privacy):
- IP anonymization
- Data retention policies
- GDPR compliance tools

Scheduled Reports Configuration

Configure email reports in plugins/ScheduledReports/:

// Example report configuration
$reportType = 'email';
$reportFormat = 'pdf'; // or html, csv
$reportPeriod = 'week';
$reportEmailMe = true;

4. Build & Run

Development Environment

Start the DDEV environment:

ddev start
ddev composer install
ddev exec php console plugin:activate VisitorGenerator

Generate test data:

# Enable VisitorGenerator plugin first
ddev exec php console core:generate-test-data --website-id=1 --days=30

Run tests:

# PHP unit tests
./console tests:run-unit

# UI tests
./console tests:run-ui

Production Build

Optimize performance:

php console core:clear-caches
php console core:archive

Set up cron jobs for archiving:

# Add to crontab (run every hour)
0 * * * * /usr/bin/php /path/to/matomo/console core:archive --url=https://yourdomain.com/matomo/

Enable plugins via CLI:

php console plugin:activate CustomAlerts
php console plugin:activate WhiteLabel

5. Deployment

Recommended Platforms

Self-Hosted Options:

Traditional VPS/Cloud Server (DigitalOcean, Linode, AWS EC2, Google Cloud)
- Ubuntu/Debian with Apache/Nginx
- MySQL/MariaDB database
- Regular backups required

Docker Deployment:

docker run -d \
  --name matomo \
  -p 80:80 \
  -v matomo_data:/var/www/html \
  -v matomo_db:/var/lib/mysql \
  matomo:latest

Managed WordPress Hosting (with PHP/MySQL support)

Matomo Cloud (Hosted Solution):

21-day free trial: https://matomo.org/start-free-analytics-trial/
No server management required
Starts at $19/month

Deployment Checklist

Pre-deployment:

# Backup database
mysqldump -u username -p database_name > matomo_backup.sql

# Backup files
tar -czf matomo_backup.tar.gz /path/to/matomo/

Update existing installation:

# Use built-in updater or
php console core:update

Post-deployment verification:
- Test tracking code
- Verify cron jobs
- Check report generation
- Validate SSL certificate

Scaling Considerations

High traffic sites: Enable database replication
Multiple servers: Use shared storage for tmp/ directory
Load balancing: Configure session storage in database
CDN: For static assets and heatmaps

6. Troubleshooting

Common Issues and Solutions

1. Installation Wizard Not Appearing

# Check PHP requirements
php -m | grep -E "pdo|mysql|gd|xml"

# Verify file permissions
chown -R www-data:www-data /path/to/matomo/
chmod -R 755 /path/to/matomo/tmp/

2. Database Connection Errors

; Verify config/config.ini.php settings
[database]
host = "localhost"
port = 3306

3. Tracking Data Not Appearing

Verify JavaScript tracking code is installed
Check browser console for errors

Ensure cron jobs are running for archiving:

php console core:archive --force-all-websites

4. Scheduled Reports Not Sending

# Check report logs
tail -f /path/to/matomo/tmp/logs/matomo.log

# Test email configuration
php console scheduled-reports:send

5. Performance Issues

# Clear caches
php console core:clear-caches

# Optimize database tables
php console database:optimize-tables

# Check archive bloat
php console core:purge-old-archive-data

6. PDF Report Generation Fails

# Ensure TCPDF dependencies are installed
# Check PHP memory limit (increase if needed)
php -i | grep memory_limit

# Verify write permissions
chmod 755 /path/to/matomo/tmp/assets/

7. Plugin Installation/Update Errors

# Check PHP requirements
php console diagnostics:run --all

# Manually install plugin
php console plugin:activate PluginName

Getting Help

Community Forums: https://forum.matomo.org/
Documentation: https://matomo.org/docs/
Professional Support: https://matomo.org/support-plans/
Security Issues: https://matomo.org/security/

Log Files Location

Application logs: tmp/logs/
PHP error logs: Check your PHP configuration
Access logs: Web server logs (e.g., /var/log/apache2/access.log)

Quick Diagnostics

# Run comprehensive diagnostics
php console diagnostics:run --all

# Check system requirements
php console diagnostics:analyze-requirements

# Verify installation integrity
php console diagnostics:check-files-integrity

How to Deploy & Use matomo