How to install Matomo Analytics on a local server?
Ok, ok, I guess you wish you could install Matomo on a real server. But you have to take into consideration that it means that you should all have paid for a real server and I wish to make this course as accessible as possible to everyone, so I prefer to guide you through the local installation only. Main advantages are:
- it won't cost you anything.
- you can work offline.
- you can break it, no one will tell you anything.
- it does not much differ from a real installation.
Main drawbacks are:
- it won't be in https by default.
- you will still have the feeling that you haven't seen everything.
How to install Matomo on a GNU/Linux Ubuntu local server?
This installation guide is for GNU/Linux Ubuntu distributions. If you are running Microsoft Windows or MAC operating systems, please install VirtualBox https://www.virtualbox.org/ in order to emulate a GNU/Linux distribution. It will be a great opportunity to discover the wonderful world of GNU/Linux.
Note that you can also install Matomo on Windows and Mac OS computers by running local servers such as Xamp: https://www.apachefriends.org/index.html
You may be interested in installing Matomo On-Premise on your own machine for the following reasons:
- You want to test Matomo On-Premise without deploying it on a web hosting platform on the internet.
- You would like to test, hack and see the inside of Matomo Analytics.
- You would like to work on Matomo offline.
In order to run, Matomo needs to be installed on a server. As we are installing it on our own computer, our computer will play the role of the client and the role of the server. This server will run on an Operating System which is GNU/Linux Ubuntu. This
OS is needed in order to run the different software including Matomo.
Matomo is not that difficult to install on a local server but what may be difficult is the installation of the server if you don't have one yet. Matomo it is not a 100% independent
software it needs a server to run on it with a specific configuration. So in order to install this server and this configuration you will need to have:
- Apache.
- MySQL.
- PHP.
To make it simple, this is what we need to go through in order to install Matomo:
It may seems like a lot of work compared to other proprietary solutions such as Google Analytics, but this is exactly where the difference is between those two solutions.
With Matomo, you are in control of everything and you can act at every level of the solution. Nothing is hidden, you have access to everything.
The good news is that many Free software are going through the same installation process, for example
that's the case with WordPress. So what you can learn here can be reproduce on many other projects and is a knowledge you can capitalize on.
OK. Let’s see how to install those three components before moving to the installation of Matomo.
Apache
Apache is a web server, without it, your browser won’t be able to make calls to Matomo so no possibility to connect. Installing Apache is really straightforward, all you need to do is to run the following command in a shell:
sudo apt install apache2
Once done, open your browser and enter localhost within your address bar and validate. If you can see a page telling you that Apache is installed… you won.
MySQL
Once Apache is installed you need to install MySQL. Why that? Because MySQL is a DBMS, a Database Management Software, without it Matomo could not store any data. In order to install MySQL you need to run the following command in a terminal:
sudo apt-get install mysql-server
Normally there are extra steps you should go for as the default configuration of the MySQL server is not secured, but as we are installing it on your own machine, it should be all right for the scope of this tutorial.
PHP
Matomo runs with PHP, a programming language in order to discuss with a database, here MySQL, so without it, no request could be executed properly. To install it you need to run:
sudo apt-get install php libapache2-mod-php
Congratulations, PHP is now normally installed on your web server. To ensure that please restart your server with the following command:
sudo systemctl restart apache2
Ready to install Matomo on your local server
Ok so now we have a server which supports PHP and has also a database management system software. We need now to install Matomo on it. First step is to get into the folder where Matomo will be installed:
cd /var/www/html/
Once you are there you can download Matomo within it, technically you could do it without the terminal and use the graphic interface of your operating system, but always better to use the terminal:
wget https://builds.matomo.org/matomo.zip
As
you can see Matomo is a zip file so you need to extract those files:
sudo unzip matomo.zip
Once done perform:
ls
As you can see Matomo has been extracted and you now have a folder named matomo. You can now enter within your browser localhost/matomo to see the installation process.
Step 1
Step 1 is very easy, you just need to click on the Next button.
Step 2 System Check
Depending on your server configuration, this step can be a mess. When you see a warning message it means that Matomo won't let you move forward. The most common mistakes you are going to see is that the PDO/MYSQLI extensions are missing, to fix that,
execute within the terminal:
sudo apt-get install php-mysql
Once done add the following three lines to the php.ini file, you will find it within /etc/php/your-php-version/apache2/. Once the lines are added to the file restart the server
with:
sudo systemctl restart apache2
Once done those error messages will disappear but you may face another one about mbstring. In order to install this extension run:
sudo apt-get install php-your-version-mbstring
Once
done then activate this feature by uncommenting it within your php.ini file. Ok now restart your server with:
sudo systemctl restart apache2
and you are good to go for step 3 as other warnings are optionnal.
Step 3 the database
Ok so here Matomo is asking you a lot of questions you probably don't want to answer to... but you have no choice. First question is what is your server database location, in your case it is localhost so 127.0.0.1. Then what is the login to connect, by
default when you installed your MySQL server the login is root. But high chances that it won't work for security reasons so you will have to create one in mysql, so you need to go to your terminal and run:
sudo mysql
Then on mysql run:
CREATE
USER 'john'@'localhost' IDENTIFIED BY 'johndoe';
So now you have a user named john and password johndoe (enter more than 6 caracters for the password as a best practice), but he has no rights for the database so you need to run:
GRANT
ALL PRIVILEGES ON matomo.* TO 'john'@'localhost';
Ok and now in order to anticipate the next question run also:
Create database your-database-name
it will create a database with the named you mentioned. If you are not happy with
the name you gave to your database please perform:
DROP DATABASE nameofyourdatabase;
to delete it. If you are not sure about the name you gave to your database, you can always list them with:
SHOW DATABASES;
Ok so now you
can go back to the Matomo installation process. So enter the login, the password and the database name and click on Next.
Step 4 Tables creation
Normally nothing to do here.
Step 5 Matomo super user creation
At this step you are defining the credentials for your super user in Matomo, so this user is different from the one of the database.
Step 6 Website configuration
Insert whatever you want here, no big deal.
Step 7 Tracking code
Here is the tracking code, that you need to have on your website in order to send the data to Matomo.
In general, one will ask you to include this code within the <head></head> part of your website. First thing to know is that in general you won't use this tracking code but the one of the Tag Management System you choose, which is called a container. The second thing is that one is asking you to insert it within the <head></head> as it represents the part of a web page which is loaded first, so it will ensure the data collection. Note though that if your code is buggy, putting it within the <head></head> will probably break your page that's the reason why some solutions are asking you to put it at the beginning of the <body> or at the end of </body>. What is the best? Once more it really depends of your infrastructure and what you would like to achieve at the end of the day. In one scenario you are getting all the data but are providing a less good experience to your end user in the other one less data but a better experience. As you do not want to spend ages on this task, just take a decision and move forward.
Note though that of course if a tracking code is not inserted on a web page then no data can be collected about this given page. Note though in some specific cases it can also spoil your data overall as the internet user will be consider has getting out of your website, so you will need to tweak your configuration files to avoid this.
Note also that this part about inserting the tracking code on your website is sometimes made directly through what we call a plugin, this really depends of the CMS you are using. In some cases those plugins let you insert whatever tracking code you want, in some others they are just providing you a template. A template for a TMS tracking code should let you the flexibility you need in order to track mostly everything you need, in the other case, unfortunately you are relying on the expertise of the plugin developer, so they are often imposing you their way of thinking which result in less possibilities in terms of data collection. Always look at the last update date of the plugin.
Step 8 Congratulations
Have fun and congratulations. Matomo is set up and running, try to push some data within it. Normally nothing special at this step, it is just confirming you that the tables have been created. Congratulations.
How to uninstall Apache/PHP/MySQL?
Ok, so you tried to install Matomo and it did not work and you would like to clean your local machine? Here are the different steps you need to go through in order to uninstall Apache:
sudo service apache2 stop
So first you need to stop
Apache.
sudo apt-get purge apache2 apache2-utils apache2.2-bin apache2-common
It will remove Apache.
sudo apt-get autoremove
This part will remove all the other dependencies. Then you need to check if there are still some
folders of Apache still installed so run:
whereis apache2
As you will probably get some results, please perform for each the following command:
sudo rm -rf /location-of-the-folder
To uninstall MySQL:
sudo apt-get
remove --purge mysql*
sudo apt-get purge mysql*
sudo apt-get autoremove
sudo apt-get autoclean
sudo apt-get remove dbconfig-mysql
To uninstall PHP:
By removing Apache and MySQL you will probably remove PHP, but always check
if with a:
whereis php
You can still find some php folders and remove them.