Matomo On-Premise (self-hosted)

Self-host Matomo Analytics on your own servers to ensure data remains in your hands! It’s for this reason that Matomo On-Premise is, and forever will remain free to download.

In the guides below you will learn how to install Matomo on your servers (Linux Debian or Windows instructions are provided), including instructions around maintaining Matomo including securing your service, updating to the latest version, customising Matomo with plugins and themes and all troubleshooting FAQs.

You will also find advanced documentation on improving performance and building a scalable Matomo architecture. With 10% of the top 10,000 websites in the world use Matomo On-Premise for their analytics, with the community's help, we've documented all our knowledge from running Matomo at scale.

 

Requirements

Requirements for Matomo On-PremiseIs Matomo Analytics compatible with Amazon AWS, Google Cloud, Azure, Rackspace, Openstack Cloud, Alibaba Cloud or my Private Cloud infrastructure?Is Matomo compatible with Windows, IIS, Apache, or Nginx?Use Docker containers to setup and run the Matomo Analytics applicationDeploy Matomo in AWS CloudIs Matomo compatible with Nginx?Find out which version of PHP I haveDo I need to use PHP on my websites to use Matomo? Pre-deployment checklist for a successful Matomo setup

Install Matomo

Installing Matomo On-Premise Set up Auto-Archiving of Your ReportsIs there a Video that explains how to Install Matomo?How long does it take to install Matomo?Is Matomo available as one click installation in cPanel, Softaculous, Webmin or other tools? Post-deploy checklist for your Matomo instanceDo I need to create a MySQL database?Create a new database and database user in MySQLInstall Matomo with PleskInstall MySQL server on Debian or Ubuntu serverInstall Matomo on Debian GNU/Linux serversMonitor that Matomo service is up and runningHow can I reinstall Matomo? Can I keep the existing data?Is the Matomo JavaScript Tracker CSP (Content Security Policy) compatible and how do I set it up?Uninstall MatomoConfigure Matomo on a server without InternetHow do I send Matomo emails using SMTP server? (for example using Gmail SMTP)Configure outgoing (forward) proxy in Matomo (eg. squid)Configure my server to let Matomo serve HTML filesMake the diagnostic « Managing processes via CLI » to display OkConfigure Matomo when mod_security (or CA SiteMinder) is enabledUse Matomo without installing the platform on a serverHow to activate all the recommended official Matomo plugins automatically after installation? (bash script)FAQ: How to disable HTTPS for matomo.org requests?

Matomo on Windows

Install and configure MySQL on Windows for MatomoInstall and configure PHP on Windows for MatomoInstall and configure IIS on Windows for MatomoSetup a scheduled task to process reports on Windows for Matomo

Scalable Matomo Setup

Configure Matomo for High availability multi server environment Configure pair of databases (Reader and Writer) in MatomoConfigure Matomo when the server is installed behind a proxyKeep the config file and tracker JS files in sync in multi-server environmentDeploy same code base on all the servers in multi-server environmentConfigure Matomo to use Redis for better Tracking API scalabilityConfigure Redis as a shared cache in a load balanced environmentConfigure Redis for session handling in a load balanced environmentConfigure Matomo Tracking for high reliabilityMulti Tenant Setup for Matomo (advanced) 

Secure Matomo

Force Matomo to use SSL (https) for improved security Configure Matomo for securityCheck that my Matomo SSL Server is correctly configuredPrevent Super Users from doing specific high risks administrative actions

Improve performance

Configure Matomo for speedRecommended settings for Matomo on high traffic websites with millions of page viewsMake Matomo fasterDoes Matomo work in a load balanced environment? Multiple servers high scale trackingHow do I delete historical Matomo data? (data retention for old web analytics raw data logs and/or old processed reports)Configure Matomo to handle unexpected peak in trafficMatomo is slow! It takes a long time to load widgets, reports and pages.Make « Transitions » feature work faster on high traffic websitesGet LOAD DATA INFILE to work on my serverDisable the OPTIMIZE queries which take too long on my serverImprove the load time of the find visitor SQL query when visitors have many visits

Update Matomo

Update MatomoKnow when new versions are releasedWhen is the next release of Matomo? What is the release schedule?Tips and considerations for updating a high traffic Matomo serverHow long is each release of Matomo maintained (LTS)?What should I do when I want to update Matomo to the latest version?I would like to test early beta and RC releases, how do I enable automatic updates to use these development versions?Verify the cryptographic PGP signature of Matomo packagesEnable Maintenance mode (to display a maintenance message in Matomo, and disable tracking) prior to updatesHow do I upgrade a large Matomo instance without losing any tracking data? (no Tracking API downtime)Manually apply database updates for a new Matomo version

Update Matomo Troubleshoot

After I updated Matomo, it stopped working (blank page, widgets not loading, error message, etc.). How can I fix this?After the update, I get sql errors, I would like to try the update again. How do I force Matomo to re-upgrade the database from a past version?Recover the missing data during Matomo maintenanceWhat should I do when the upgrade failed with « Syntax error or access violation: 1142 INDEX command denied to user »Disable the update notification email when a new Matomo version is releasedDowngrade from Matomo 4 to Matomo 3Resolve the error: Illegal mix of collations … for operation ‘=’

Maintenance

Backup and restore the Matomo dataRestore my MySQL databaseBackup my MySQL databaseBackup Matomo data and filesMomentarily disable Matomo User Interface and/or Matomo visitor TrackingBackup Matomo best practises – what to backup and how oftenView Matomo application logsWhen to trigger an alert when monitoring Matomo servers?Requirements for server infrastructure and capacity planningHow do I use the console tools in Matomo? Which console tools are available in Matomo by default?Find diagnostic information for report archivingImportant Logs to enable and backupSetup a staging instanceEnable MySQL slow query logs for MatomoHow long does the Matomo archiving process take for high traffic websites – or hundreds of websites?Clear the various caches in MatomoPrevent Matomo from sending any email, when testing Matomo on a staging/non-prod environmentGet the DB-IP databases or Maxmind GeoIp2 to improve accuracy of Country detection, and detect visitors’ Cities and RegionsDelete old visitors statistics for a given website and/or dateReplay the traffic to Matomo and ingest logs of matomo.php (or piwik.php) requestsMonitor errors from Matomo CRON tabsSetup Auto-Archiving script to run using systemd on a Linux system instead of cron

Migrate

Move Matomo from one server to another, also migrating the data from one MySQL server to another Migrate from Google Analytics to MatomoI want to migrate Matomo and move it to a new domain or a new subdomain URL, with the same MySQL server. How should I proceed?Migrate a particular website in Matomo to a different Matomo installationMove my data between Matomo On-Premise & CloudImport logs with a different idsiteInstall Matomo on one server and track visits on websites that are hosted on other servers

Customise Matomo

After the top 500 or top 1000 rows, Matomo automatically groups pages, keywords, websites, etc. under the label « Others »; How do I force Matomo to not limit the data?I would like to import an existing Users database (login, password, emails) in Matomo, but the usernames and passwords are more permissive than what Matomo allows. How do I disable the checks on the Logins & Passwords?A search engine is counted as a website referrer. How can I add the search engine to Matomo?Customise the JavaScript Tracker code on all websites at onceConfigure a config setting in the config.ini.php differently for a specific siteChange the default email address « From: » in PDF/HTML email reports and other emails sent by MatomoChange the default email address “From:” in password reset emailsInclude & Customize Matomo for your Project

How to

Find and edit « config.ini.php »: The Matomo configuration fileCustomise any text label such as menus, report names, column names, event names and values, custom dimension names, custom report names, dashboard names and moreMake sure Search engines robots do not index Matomo serverTrack and measure how my Matomo service is being usedTell Matomo to invalidate the past historical reports so they can be re-processed from the logsPrevent Matomo from creating a new visit after 10000 actionsDisable all automated emails so that Matomo doesn’t send any emailUse Matomo from the official Git repositoryUse the database to store session filesRotate and backup logs to avoid log files becoming very largeDisable archiving the segment reports for specific pluginsSend emails through SMTP server with self-signed SSL certificate

Database

Managing your database’s sizeBackup my MySQL databaseRestore my MySQL databaseCheck if my MySQL user has all required grantsSetup Matomo to securely connect to the database using MySQL SSLSpecify to use Mysql on a custom port or to connect Mysql over a socketGet LOAD DATA INFILE to work on my serverAutomatically stop long running database queriesHow do I use another database like PostgreSQL, SQLite, Oracle? Will you support NoSQL databases like Hadoop, MongoDB?Install Matomo using TokuDB table engine in a MySQL or MariaDB databaseConvert the database to utf8mb4 charsetSelect IP addresses or Visitor ID from the SQL database and convert binary table fieldsManually apply database updates for a new Matomo version

Troubleshoot Matomo

Find and copy the system check in Matomo On-Premise I get ‘Oops… there was a problem during the request.’ or ‘Internal Server Error’ or ‘500 error’ or the ‘White screen of death’. How do I proceed?Matomo does not track visits on SSL / HTTPS pages.Matomo reporting UI doesn’t have any css style or, the menu text appears on a white background, or I get JavaScript errors in the Matomo UI. How to fix this display problem?Enable unicode characters (Japanese, Chinese, Russian, Hebrew, Arabic, etc.) in graphs in PDF/HTML reports and Matomo Mobile graphsSparklines (evolution graphs) are missing in the Matomo dashboard.Emails from Matomo are not being sent, how do I troubleshoot and solve the issue?I’m a developer, how do I enable logging (and / or SQL profiling) in Matomo?Graphs in PDF/HTML reports and/or Matomo Mobile do not display characters correctly in my language (display squares instead).Why am I getting a warning about an untrusted hostname?Find the cause of the Brute Force detection blocking access from a specific IPAntivirus program or malware checker or Google Ads claim that matomo.js or piwik.js are malware, what can I do?Matomo is slow after creating a custom report, funnel or installing users flowWhy some pages or actions show a lower pageviews metric, but for a longer time period?Matomo doesn’t show me when new updates are available, and the SEO plugin doesn’t work.Almost all reports and dates are working fine except one or a small number of days/weeks/months/date ranges which display zero visit. How do I fix this issue and restore the missing data?Force the reports to be re-processed from the logsAll visitors have the same IP address and Provider. How do I track individual IPs?How do I fix that the time is off by one hour? (timezone that doesn’t use the correct offset)I get the error Warning: Unexpected character in input: ‘\’ (ASCII=92) state=1Matomo reports this error and doesn’t continue: « Fatal error: Maximum execution time of 30 seconds exceeded in … »Fix the error « Call to undefined method MaxMind\Db\Reader::getWithPrefixLen() »Matomo reports this error and fails: « Fatal error: Allowed memory size of X bytes exhausted (tried to allocate X bytes) ». What should I do?Emails sent from Matomo use the email address @defaultHostnameIfEmpty.example.org, how do I specify my domain name instead?Fix the error « Parse error: syntax error, unexpected T_STRING in … »I get the error message: « Fatal error: require_once() [function.require]: Failed opening required XYZ in /path/piwik/XYZ.php on line X ». How can I get Matomo to work?« Segmentation fault Error ». Matomo reporting or via cron crashes with Segmentation Fault error. What to do?Fix the errors « Unable to write in the cache directory » or « The directory matomo/tmp/cache/* » is not writable. »I get: PHP Fatal error Call to undefined function imagecreatefrompng()I get the error message: « Fatal error: Class ‘not found in … ». What’s wrong?Fix the error « SMTP Error: Could not authenticate. »Fix the error ‘Fatal error: Maximum function nesting level of ‘100’ reached, aborting!’I get the error « Warning: gzuncompress() [function.gzuncompress]: data error » when looking at my Matomo reports.Fix the error private directories are accessibleWhy many of my visits have « 0 Action » in Matomo and how do I fix this issue?Fix timeout errors when trying to create a user auth tokenTroubleshoot when Chrome shows a warning on your Matomo domain

Troubleshoot Database

Fix the error « Mysql Server has gone away »Fix the Mysql error « Connection refused »Fix the Mysql « Error while sending QUERY packet »Fix the error « General error: 3 Error writing file /tmp/xyz (Errcode: 28 – No space left on device) »What should I do when I get the error message: SQLSTATE[HY000] [2002] Can’t connect to local MySQL server through socket ‘/var/lib/mysql/mysql.sock’ (11)Fix the error « 1118 Row size too large. The maximum row size for the used table type, not counting BLOBs, is 8126. »I get the error: ERROR 1034 (HY000): Incorrect key file for table ‘matomo_log_visit’; try to repair it OR Table matomo_log_x is marked as crashed and last (automatic?) repair failedConvert the MySQL database tables from MyIsam to InnoDBFix « SQLSTATE[HY000][2054] The server requested authentication method unknown to the client » error

Troubleshoot SSL

How do I fix the error ‘Unable to find the wrapper « https » – did you forget to enable it when you configured PHP?’Fix the issue « Response was ‘curl_exec: SSL certificate problem: unable to get local issuer certificate. Hostname requested was: » in the archiverWhat to do when you see curl: (60) SSL certificate problem: unable to get local issuer certificate error?Fix « curl_exec: Peer’s Certificate issuer is not recognized… Hostname requested was: plugins.matomo.org »When I use force_ssl=1, I get « Too many redirects ». Also when I use https, CSV/PDF reports and graphs don’t work.

Support Plans

Paid support for Matomo On-PremiseWhat are « actions » in Matomo? How do I find my number of actions per month?

Plugins and Themes

List of Matomo pluginsInstall a new pluginInstall a new ThemeActivate a new plugin in multi servers environmentDisable a pluginUninstall a pluginReport a bug in a pluginWhat are Premium plugins? How do they differ from open source/free plugins?Free trial and purchase Matomo Premium FeaturesInstall a Matomo Premium FeatureWhat is the Matomo Marketplace?Get started building a plugin for the Matomo platformKnow whether the plugins I use are compatible with the latest Matomo versionAre all premium features supported by the Android and iOS SDKs?View historical reports after installing a new plugin