What is Matomo?
Matomo (formerly known as Piwik) is a leading open-source web analytics platform that provides a privacy-focused alternative to Google Analytics. It gives you complete control over your data while offering comprehensive website analytics capabilities.
Key Features:
- 100% Data Ownership: All data stays on your servers
- Privacy Protection: GDPR-compliant with advanced privacy controls
- Real-time Analytics: Live visitor tracking and behavior analysis
- E-commerce Tracking: Advanced online business analytics
- Goal & Campaign Tracking: Conversion optimization tools
- Custom Variables & Segments: Flexible data analysis
- Geolocation & Maps: Real-time visitor location tracking
- Email Reports: Automated analytics delivery
- Extensible Platform: Plugin system for customization
Docker Installation Options
There are two main Docker approaches for installing Matomo:
- Official Matomo Docker Image – Maintained by the Matomo team
- Bitnami Matomo Image – Enterprise-grade image by VMware
Prerequisites
Before starting, ensure you have:
- Docker Engine >= 1.10.0
- Docker Compose >= 1.6.0
- At least 2GB RAM available
- 10GB+ disk space for data storage
Check your Docker installation:
|
1 2 3 4 |
docker --version docker-compose --version |
Method 1: Official Matomo Docker Image
Basic Docker Compose Setup
Create a project directory and docker-compose.yml:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 |
version: '3.8' services: db: image: mariadb:10.11 command: --max-allowed-packet=64MB restart: always volumes: - db_data:/var/lib/mysql environment: - MYSQL_ROOT_PASSWORD=your_strong_password_here - MYSQL_DATABASE=matomo - MYSQL_USER=matomo - MYSQL_PASSWORD=matomo_password - MARIADB_AUTO_UPGRADE=1 - MARIADB_DISABLE_UPGRADE_BACKUP=1 networks: - matomo_network matomo: image: matomo:latest restart: always depends_on: - db ports: - "8080:80" volumes: - matomo_data:/var/www/html - ./logs:/var/www/html/logs environment: - MATOMO_DATABASE_HOST=db - MATOMO_DATABASE_ADAPTER=mysql - MATOMO_DATABASE_TABLES_PREFIX=matomo_ - MATOMO_DATABASE_USERNAME=matomo - MATOMO_DATABASE_PASSWORD=matomo_password - MATOMO_DATABASE_DBNAME=matomo - PHP_MEMORY_LIMIT=2048M networks: - matomo_network volumes: db_data: matomo_data: networks: matomo_network: driver: bridge |
Production-Ready Configuration with Nginx
For production deployment with SSL support:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 |
version: '3.8' services: db: image: mariadb:10.11 command: --max-allowed-packet=64MB restart: always volumes: - db_data:/var/lib/mysql environment: - MYSQL_ROOT_PASSWORD=your_strong_password_here - MYSQL_DATABASE=matomo - MYSQL_USER=matomo - MYSQL_PASSWORD=matomo_password - MARIADB_AUTO_UPGRADE=1 - MARIADB_DISABLE_UPGRADE_BACKUP=1 networks: - matomo_network matomo: image: matomo:fpm-alpine restart: always depends_on: - db volumes: - matomo_data:/var/www/html - ./logs:/var/www/html/logs environment: - MATOMO_DATABASE_HOST=db - MATOMO_DATABASE_ADAPTER=mysql - MATOMO_DATABASE_TABLES_PREFIX=matomo_ - MATOMO_DATABASE_USERNAME=matomo - MATOMO_DATABASE_PASSWORD=matomo_password - MATOMO_DATABASE_DBNAME=matomo - PHP_MEMORY_LIMIT=2048M networks: - matomo_network nginx: image: nginx:alpine restart: always depends_on: - matomo ports: - "80:80" - "443:443" volumes: - matomo_data:/var/www/html:ro - ./nginx.conf:/etc/nginx/nginx.conf:ro - ./ssl:/etc/nginx/ssl:ro networks: - matomo_network volumes: db_data: matomo_data: networks: matomo_network: driver: bridge |
Method 2: Bitnami Matomo Docker Image
Basic Bitnami Setup
The Bitnami image provides enterprise-grade security and stability:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 |
version: '3.8' services: mariadb: image: bitnami/mariadb:10.11 restart: always environment: - ALLOW_EMPTY_PASSWORD=no - MARIADB_ROOT_PASSWORD=your_strong_password_here - MARIADB_DATABASE=matomo - MARIADB_USER=matomo - MARIADB_PASSWORD=matomo_password volumes: - mariadb_data:/bitnami/mariadb networks: - matomo_network matomo: image: bitnami/matomo:latest restart: always depends_on: - mariadb ports: - '8080:8080' - '8443:8443' environment: - MATOMO_DATABASE_HOST=mariadb - MATOMO_DATABASE_PORT_NUMBER=3306 - MATOMO_DATABASE_USER=matomo - MATOMO_DATABASE_PASSWORD=matomo_password - MATOMO_DATABASE_NAME=matomo - MATOMO_USERNAME=admin - MATOMO_PASSWORD=admin_password - MATOMO_EMAIL=admin@example.com volumes: - matomo_data:/bitnami/matomo - matomo_logs:/opt/bitnami/matomo/logs networks: - matomo_network volumes: mariadb_data: matomo_data: matomo_logs: networks: matomo_network: driver: bridge |
Enhanced Bitnami Configuration
For production with additional security and performance features:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 |
version: '3.8' services: mariadb: image: bitnami/mariadb:10.11 restart: always environment: - ALLOW_EMPTY_PASSWORD=no - MARIADB_ROOT_PASSWORD=your_strong_password_here - MARIADB_DATABASE=matomo - MARIADB_USER=matomo - MARIADB_PASSWORD=matomo_password - MARIADB_EXTRA_FLAGS=--max-allowed-packet=64MB --innodb-buffer-pool-size=1G volumes: - mariadb_data:/bitnami/mariadb networks: - matomo_network deploy: resources: limits: memory: 1G matomo: image: bitnami/matomo:latest restart: always depends_on: - mariadb ports: - '8080:8080' - '8443:8443' environment: - MATOMO_DATABASE_HOST=mariadb - MATOMO_DATABASE_PORT_NUMBER=3306 - MATOMO_DATABASE_USER=matomo - MATOMO_DATABASE_PASSWORD=matomo_password - MATOMO_DATABASE_NAME=matomo - MATOMO_USERNAME=admin - MATOMO_PASSWORD=admin_password - MATOMO_EMAIL=admin@example.com - MATOMO_HOST=your-domain.com - MATOMO_SKIP_BOOTSTRAP=no - PHP_MEMORY_LIMIT=2048M - PHP_POST_MAX_SIZE=64M - PHP_UPLOAD_MAX_FILESIZE=64M volumes: - matomo_data:/bitnami/matomo - matomo_logs:/opt/bitnami/matomo/logs - ./matomo-config:/bitnami/matomo/config networks: - matomo_network deploy: resources: limits: memory: 2G volumes: mariadb_data: matomo_data: matomo_logs: networks: matomo_network: driver: bridge |
Installation Steps
1. Create Project Directory
|
1 2 3 4 |
mkdir matomo-docker cd matomo-docker |
2. Choose and Create Docker Compose File
Copy one of the configurations above into a docker-compose.yml file.
3. Configure Environment Variables
Create a .env file for sensitive data:
|
1 2 3 4 5 6 7 8 9 10 11 |
# Database Configuration MYSQL_ROOT_PASSWORD=your_super_strong_root_password MYSQL_PASSWORD=your_strong_matomo_password MATOMO_DATABASE_PASSWORD=your_strong_matomo_password Matomo Configuration MATOMO_USERNAME=admin MATOMO_PASSWORD=your_admin_password MATOMO_EMAIL=admin@yourdomain.com MATOMO_HOST=yourdomain.com |
4. Start Services
|
1 2 3 4 5 6 7 8 |
# Start in detached mode docker-compose up -d View logs docker-compose logs -f Check status docker-compose ps |
5. Access Matomo
- Development: http://localhost:8080
- Production: https://yourdomain.com
Initial Configuration
Database Setup (Official Image)
When accessing Matomo for the first time, use these database settings:
- Database Server:
db(ormariadbfor Bitnami) - Username:
matomo - Password:
matomo_password(your configured password) - Database Name:
matomo - Table Prefix:
matomo_ - Adapter:
PDO\MYSQL
Bitnami Auto-Configuration
The Bitnami image automatically configures the database connection using environment variables, so you can skip the database setup step.
Security Best Practices
1. Change Default Passwords
Never use default passwords in production:
|
1 2 3 4 5 6 |
# Update passwords in .env file # Restart containers docker-compose down docker-compose up -d |
2. Configure Trusted Hosts
Edit the Matomo configuration to add trusted hosts:
|
1 2 3 4 5 6 |
// config/config.ini.php [General] trusted_hosts[] = "yourdomain.com" trusted_hosts[] = "localhost:8080" |
3. Use SSL/TLS
Always use HTTPS in production:
- Configure SSL certificates
- Set up proper nginx configuration
- Use Let’s Encrypt for free certificates
4. Regular Backups
Set up automated backups:
|
1 2 3 4 5 6 |
# Database backup docker exec matomo_db_1 mysqldump -u matomo -p matomo > backup.sql Volume backup docker run --rm -v matomo_data:/data -v $(pwd):/backup alpine tar czf /backup/matomo-backup.tar.gz /data |
Maintenance Commands
Update Matomo
|
1 2 3 4 5 6 7 |
# Pull latest images docker-compose pull Restart with new images docker-compose down docker-compose up -d |
Database Maintenance
|
1 2 3 4 |
# Access database docker exec -it matomo_db_1 mysql -u matomo -p matomo |
|
1 2 3 4 |
# Optimize tables OPTIMIZE TABLE matomo_log_visit, matomo_log_action, matomo_log_conversion; |
Log Management
|
1 2 3 4 5 6 |
# View Matomo logs docker-compose logs matomo Rotate logs docker exec -it matomo_matomo_1 find /var/www/html/logs -name "*.log" -mtime +30 -delete |
Performance Optimization
1. Database Optimization
|
1 2 3 4 5 |
-- Add indexes for better performance CREATE INDEX idx_idsite_date ON matomo_log_visit(idsite, visit_last_action_time); CREATE INDEX idx_idsite_userid ON matomo_log_visit(idsite, user_id); |
2. Caching Configuration
Enable caching in Matomo:
|
1 2 3 4 5 6 7 |
[General] enable_framed_pages = 1 enable_framed_logins = 1 enable_maintenance_mode = 0 cache_backend = file |
3. Archive Processing
Set up automated archiving:
|
1 2 3 4 |
# Add to crontab */5 * * * * docker exec matomo_matomo_1 php /var/www/html/console core:archive --url=https://yourdomain.com |
Environment Variables Reference
Official Matomo Image
MATOMO_DATABASE_HOST: Database hostnameMATOMO_DATABASE_ADAPTER: Database adapter (mysql)MATOMO_DATABASE_TABLES_PREFIX: Table prefixMATOMO_DATABASE_USERNAME: Database usernameMATOMO_DATABASE_PASSWORD: Database passwordMATOMO_DATABASE_DBNAME: Database namePHP_MEMORY_LIMIT: PHP memory limit
Bitnami Image
MATOMO_DATABASE_HOST: Database hostnameMATOMO_DATABASE_PORT_NUMBER: Database portMATOMO_DATABASE_USER: Database usernameMATOMO_DATABASE_PASSWORD: Database passwordMATOMO_DATABASE_NAME: Database nameMATOMO_USERNAME: Admin usernameMATOMO_PASSWORD: Admin passwordMATOMO_EMAIL: Admin emailMATOMO_HOST: Domain nameMATOMO_SKIP_BOOTSTRAP: Skip initial setup
Production Deployment Checklist
- Use strong passwords for all services
- Configure SSL/TLS certificates
- Set up proper firewall rules
- Configure trusted hosts
- Set up automated backups
- Configure monitoring and alerting
- Set up log rotation
- Configure automated archiving
- Test disaster recovery procedures
- Document configuration and procedures
Useful Resources
- Official Matomo Website
- Official Matomo Docker Repository
- Matomo on Docker Hub
- Bitnami Matomo on Docker Hub
- Matomo Documentation
- Matomo FAQ
Thoughts
Both the official Matomo Docker image and Bitnami’s version provide excellent options for deploying Matomo. The official image offers more flexibility and direct access to Matomo features, while Bitnami provides enterprise-grade security and easier configuration management.
Choose the approach that best fits your needs:
- Official image: For maximum flexibility and customization
- Bitnami image: For enterprise environments requiring enhanced security
Remember to follow security best practices, set up proper monitoring, and maintain regular backups for production deployments.
FAQ
What is Matomo and how does it differ from Google Analytics?
Matomo is an open-source, privacy-focused web analytics platform that gives you 100% data ownership. Unlike Google Analytics, Matomo doesn’t share your data with third parties, is GDPR compliant by design, and allows you to host your data on your own servers or in the EU. You get complete control over your analytics data without compromising visitor privacy.
What are the differences between Matomo Cloud and On-Premise?
Matomo Cloud: Hosted by Matomo, includes all premium features, automatic updates, and support. Pricing starts at $23/month for 50,000 hits. Data stored in Frankfurt, Germany.
Matomo On-Premise: Self-hosted on your servers, free core software, you manage updates and maintenance. Premium features cost extra. Complete control over data location and security.
What are the minimum requirements to run Matomo?
Basic requirements:
- Webserver (Apache, Nginx, IIS)
- PHP 7.2.5+ (PHP 8.x recommended)
- MySQL 5.5+ or MariaDB (MySQL 8+ recommended)
- 128MB PHP memory limit minimum (256MB recommended)
For high traffic (1M+ actions/month): 2 servers minimum – separate database and app servers with 4+ CPU, 8GB+ RAM each.
How do I install Matomo?
For WordPress: Install the free „Matomo Analytics“ plugin from WordPress directory – no coding required.
For self-hosted:
- Download latest Matomo from matomo.org
- Create MySQL database and user
- Upload files via FTP in binary mode
- Visit your domain/matomo in browser
- Follow installation wizard
For Cloud: Sign up at matomo.org/cloud and add tracking code to your site.
Why is Matomo not tracking any visits?
Common causes and solutions:
- JavaScript disabled: Ensure JavaScript is enabled in your browser
- Tracking code missing: Verify the tracking code is on all pages
- Wrong site ID: Check the tracking code has correct site ID (usually „1“ for first site)
- Do Not Track enabled: Disable „Support Do Not Track“ in Privacy settings
- Ad blockers: Some ad blockers block Matomo tracking
- SSL issues: Ensure HTTPS is properly configured if using SSL
Is Matomo GDPR compliant?
Yes, Matomo is GDPR compliant and has been approved by the French Data Protection Authority (CNIL). Key features:
- Data anonymization options
- Cookieless tracking available
- IP anonymization built-in
- User opt-out mechanisms
- Data retention controls
- EU data hosting (Cloud version)
Unlike Google Analytics, Matomo doesn’t transfer data to the US, making it compliant with recent EU court rulings.
How much does Matomo cost?
Matomo On-Premise: Free core software, premium plugins cost $150-200/year per site
Matomo Cloud pricing (2024):
- 50,000 hits/month: $23/month
- 100,000 hits/month: $39/month
- 500,000 hits/month: $129/month
- 1M+ hits: Custom pricing
WordPress plugin: Free basic version, premium features $189-199/year
Can I import my Google Analytics data to Matomo?
Yes, Matomo offers a Google Analytics Importer that can transfer your historical data from Universal Analytics (GA3) to Matomo. This helps preserve your historical data when switching from Google Analytics. The importer handles most standard reports and metrics.
What’s the difference between Matomo for WordPress and On-Premise?
Matomo for WordPress:
- Easier installation (plugin)
- User management via WordPress
- Automatic geolocation setup
- No manual cron jobs needed
- Limited to WordPress sites
Matomo On-Premise:
- Full feature access
- Multi-site management
- API access
- Log analytics support
- Advanced configuration options
How do I troubleshoot login issues?
Common login troubleshooting steps:
- Password reset: Use „Lost your password?“ link
- Clear cookies: Enable cookies for Matomo domain
- Disable ad blockers: Some may block login functionality
- Try HTTPS: If using HTTP, try HTTPS login
- Check proxy settings: Configure proxy headers if using proxy
- Browser cache: Clear browser cache and try again
What happens after Matomo updates?
If Matomo stops working after an update:
- Clear browser cache and cookies
- Check file permissions (644 for files, 755 for directories)
- Verify all files uploaded correctly
- Check server error logs
- Disable plugins temporarily
- Run the database update script if prompted
Cloud users get automatic updates without manual intervention.
How do I set up archiving for high-traffic sites?
For sites with 100,000+ page views per month, set up automatic archiving:
Then disable browser archiving in config:
How do I configure Matomo for GDPR compliance?
Key GDPR configuration steps:
- Anonymize IPs: Go to Privacy → Anonymize data → Enable IP anonymization
- Disable cookies: Enable „Force tracking without cookies“
- Data retention: Set automatic data deletion periods
- User consent: Implement opt-out mechanisms
- Privacy policy: Update with Matomo data collection details
Where can I get help and support?
Matomo support resources:
- Documentation: matomo.org/faq and matomo.org/help
- Community forums: Free support from community
- Professional support: Paid support plans for On-Premise
- Cloud support: Included with Cloud subscriptions
- Developer zone: API documentation and development guides
- Video tutorials: Step-by-step installation and usage guides
Can I use Matomo for free?
Yes, Matomo offers several free options:
- On-Premise: Core software completely free, host on your servers
- WordPress plugin: Free version with essential analytics features
- Cloud trial: 21-day free trial with full features
Premium features like heatmaps, A/B testing, and advanced segmentation require paid plans or plugins.
