My Trials Installing a Matomo Fork on WSL2, Windows 11

I had a matomo development environment running in an Apache virtual host in folder /var/www/matomo. I backed that up, deleted all tables in the database. Following the instructions at https://developer.matomo.org/guides/contributing-to-piwik-core I created a matomo fork in my github account.

From /var/www I ran

git clone https://github.com/myusername/matomo.git matomo
git remote add upstream https://github.com/matomo-org/matomo
composer install

I tried loading the website and got a 403 Forbidden error.

Hoping for a simple fix of permissions errors, from /var/www I ran

sudo chown www-data -R matomo

then from /var/www/matomo

chmod -R 775 *

Still got a 403 error. Checked the root folder and noticed there was no .htacess file. I copied the .htaccess file from production site into /var/www/matomo, ran the site and got the setup screen. FYI, all it contains are these two lines

RewriteEngine on
RewriteOptions inherit

Just to be safe, I also ran git submodule update --init which is in the Developer Getting Started guide, but not in contributing-to-piwik-core.

I went through the setup, and tried verifying the tracking code using the Brave brower. Nothing got logged. I switched to Chrome and visits were logged as expected.

Ran the System Check and it showed several instances of error “Unable to execute check for https://analytics.dev/config/config.ini.php: curl_exec: SSL certificate problem: unable to get local issuer certificate”.

I’ve been through this before the first time I set up a Matomo development environment. I am developing in WSL2 on Windows 11, and have easily spent 60 hours the past couple of years working our SSL issues.

A hack work around is to add

  CURLOPT_SSL_VERIFYHOST => false,
  CURLOPT_SSL_VERIFYPEER => false,

to the curl options in core/HTTP.php, begining around line 652.

Yeah I know. Its BAD. But its only my dev machine and I spent 10 hours trying to figure it out correctly with no luck.

VISITOR GENERATOR
Next I enabled the Visitor Generator, but was not in development mode because the instruction to run “./console development:enable” was not in the contributing-to-piwik-core guide and I forgot. It is in the Developer Getting Started guide.

I ran the generator and got an error page showing “SSL certificate problem: unable to get local issuer certificate”. The curl options hack worked in 4.x-dev, but not in 5.x-dev Hours of trying every solution I found on the internet availed nothing.

In my search for a solution I read Visitor Generato Changelog at https://plugins.matomo.org/VisitorGenerator/changelog, and saw

1.2.1 New workaround:
     When force_ssl is enabled, and visits are generated on localhost, 
     force to use HTTP instead of HTTPS

So out of desperation I change my 000-default.conf and default-ssl.conf files to point to the /var/www/matomo folder. In case you do not know, those are the Virtual Host files that control http://localhost. I restarted apache, ran localhost in the browser getting Matomo, ran the Visitor Generator, and it worked!!!

I reverted the changes to 000-default.conf and default-ssl.conf, restarted apache, and got localhost and my Matomo installation working as desired.

SETTING UP TESTS
Once again the Matomo documentation is scattered and incomplete. The Developer Settig Up guide at https://developer.matomo.org/guides/getting-started-part-1 say we need to add this to our config.ini.php file

[database_tests]
host = "127.0.0.1"
username = ...
password = ...

The PHP Tests page at https://developer.matomo.org/guides/tests-php says we also need to add

[tests]
http_host = "localhost"
request_uri = "/"
with some recommended changes based on specific environment. We then need to run
./console tests:setup-fixture OmniFixture

Following the instructions in the online documentation wll not work.

Your config.ini.php needs to include the following. Note you must create a database with the name defined in dbname, before running setup-fixture. The default is matomo_test, but it can have any valid db name.

[database_tests]
host = "127.0.0.1"
username = ...
password = ...
dbname = "matomo_tests"


[tests]
http_host   = localhost, or the ServerName defined in the Virtual Hosts file for the site.  In my case analytics.dev
remote_addr = "127.0.0.1"
request_uri = "/"

Even this is not enough. Running ./console tests:setup-fixture OmniFixture results in a 403 Forbidden error in /misc/log-analytics/import_logs.py. I could not figure this out. Honestly, I copied the .htaccess file from my Drupal site, and then it worked. Go figure.

After wittling down the Drupal .htaccess file, I finally got setup-fixture to run with this in the site root .htaccess file.


Options -Indexes
DirectoryIndex index.php index.html index.htm

<IfModule mod_rewrite.c>
  RewriteEngine on
  RewriteRule ^ - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
</IfModule>

I did confirm page tracking still worked, but did not try re-running the Visitor Generator.

Tried running a few tests and they worked.

./console tests:run AllWebsitesTest
./console tests:run TrackerTest
./console tests:run HttpTest

I did get an error with the HttpTest, saying the file size was incorrect and that is failed throwing an exception with an invalid certificate. That is expected as I changed the curl options in that file to not verify the certificate. The test worked as expected.

So that is my trial of getting a Matomo fork working on WSL2, Windows 11. It may well be different on other environments. Here are the final steps I took, and I understand there are a number of bad practices, but this at least got it all working.

STEPS THAT WORKED

  1. Initial Clone and Setup
git clone https://github.com/your_user_name/matomo.git matomo
cd matomo
git remote add upstream https://github.com/matomo-org/matomo
composer install
git submodule update --init
sudo chown www-data -R 
sudo chmod -R 775 *
  1. Create a .htaccess file in site root with following contents.
Options -Indexes
DirectoryIndex index.php index.html index.htm

<IfModule mod_rewrite.c>
  RewriteEngine on
  RewriteRule ^ - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
</IfModule>
  1. Only if you want to run tests. Add the following to the config/config.ini.php file
[database_tests]
host = "127.0.0.1"
username = ...
password = ...
dbname = "matomo_tests"


[tests]
http_host   = ServerName defined in the Virtual Hosts file for the site.  In my case analytics.dev
remote_addr = "127.0.0.1"
request_uri = "/"
  1. If you want a hack to clear the “curl_exec: SSL certificate problem: unable to get local issuer certificate” error, add
  CURLOPT_SSL_VERIFYHOST => false,
  CURLOPT_SSL_VERIFYPEER => false,

to the curl options in core/HTTP.php, begining around line 652.

  1. If you want to run Visitor Generator, try pointing your localhost Virtual host file to your matomo folder.
1 Like

Hi @zieder
Thanks for sharing your experiment :slight_smile:

@innocraft, @bx80, @MisterGenest maybe you can take some information in this to update the developer documentation (and / or add more information here on what has been missed) :wink:

Thanks @zieder, this is really useful information to help us improve the documentation and process for setting up a new development environment :+1:

I’ve created a new ticket to get the guide updated and address the issues you’ve raised.

1 Like