From c12a81ba71f6e1c4f86eb2f4963d9e04c5bc075d Mon Sep 17 00:00:00 2001 From: sgiehl Date: Mon, 17 Aug 2026 11:04:37 +0200 Subject: [PATCH] Make installing the proxy from a repository archive the documented way A repository checkout contains a lot that an installation does not need: the test suite, the CI configuration, coding standard rules and the git metadata itself. Installing from an archive instead keeps the installed directory to the files the proxy actually consists of. - mark the development-only files as export-ignore, so `git archive` output and the source archives GitHub attaches to releases contain only the files that belong in a web root - document the source archive as the way to install the proxy, and move the clone instructions to the contributing section - run the tests/server/ stand-in only for the test configuration it belongs to, give its non-image responses an explicit content type, and cover that with a test --- .gitattributes | 14 ++++++++++ .github/config.php | 5 ++++ README.md | 60 ++++++++++++++++++++++++++++++----------- tests/ProxyTest.php | 13 +++++++++ tests/server/matomo.php | 18 ++++++++++++- 5 files changed, 93 insertions(+), 17 deletions(-) create mode 100644 .gitattributes diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..41e8dfa --- /dev/null +++ b/.gitattributes @@ -0,0 +1,14 @@ +# Files that are only needed to develop or test the proxy. `export-ignore` keeps them out of +# `git archive` output and out of the source archives GitHub attaches to releases, so that a +# release download contains only the files that belong in a public web root. +# +# Note that this does NOT apply to `git clone` - a clone always contains everything, which is +# why the README documents the release archive as the way to install the proxy. +/tests export-ignore +/.github export-ignore +/.editorconfig export-ignore +/.gitattributes export-ignore +/.gitignore export-ignore +/.php-version export-ignore +/composer.lock export-ignore +/phpcs.xml export-ignore diff --git a/.github/config.php b/.github/config.php index fa4a713..b256c2c 100644 --- a/.github/config.php +++ b/.github/config.php @@ -33,3 +33,8 @@ if ($isTestServer && isset($_SERVER['HTTP_X_TEST_COOKIE_ALLOWLIST_INVALID'])) { $COOKIE_ALLOWLIST = $_SERVER['HTTP_X_TEST_COOKIE_ALLOWLIST_INVALID']; } + +// Exercise the test server's refusal to run for anything but a test configuration. +if ($isTestServer && !empty($_SERVER['HTTP_X_TEST_NON_TEST_CONFIG'])) { + $MATOMO_URL = 'https://matomo.example.org/matomo/'; +} diff --git a/README.md b/README.md index 122ac6e..b3d1378 100644 --- a/README.md +++ b/README.md @@ -30,14 +30,40 @@ In your Matomo server: You need to install the proxy on the server where your websites are hosted. You can do it both ways: -- download the files manually -- or install the whole repository with git +- download the source archive (recommended) +- or download the individual files manually + +| :warning: Install from the archive, not with `git clone` | +|-----------------------------------------| +| A clone of this repository contains more than the proxy: it also contains the test suite, the CI configuration and other development files, none of which belong in a public web root. The source archive contains only the files the proxy needs, so use it to install. If your existing installation contains a `tests/` directory — because it was cloned, or extracted from an older archive — remove `tests/`, `.github/`, `.git/`, `vendor/` and `composer.lock` from it, or reinstall from the archive. | | :zap: Important note about where to install the proxy | |-----------------------------------------| | To ensure the highest data accuracy possible, and that your Matomo cookies are set correctly, please install the proxy in your main website domain name and web server. This proxy should be ideally installed on your webserver directly under `{site_to_be_tracked}`. If you installed the proxy in a sub-domain under `analytics.{site_to_be_tracked}` then this would cause data to be less accurate. (Why? because if the sub-domain `analytics.{site_to_be_tracked}` was to resolve to a CNAME that does _not_ match `{site_to_be_tracked}` OR if it was to resolve to A/AAAA addresses that do not match the first half of the A/AAAA addresses running `{site_to_be_tracked}`, then the cookies set by the Matomo Tracker Proxy in the response would only have a lifetime of maximum 7 days on Safari >= 16.4.) | +#### Download the source archive (recommended) + +Download the archive into the directory you want to serve the proxy from, for example `matomo/` in your website root directory, so that the proxy ends up at `http://{site_to_be_tracked}/matomo/matomo.php`: + +```bash +cd /path/to/your/website-root +mkdir matomo +cd matomo +curl -L https://github.com/matomo-org/tracker-proxy/archive/refs/heads/master.tar.gz | tar xz --strip-components=1 +cp config.php.example config.php +``` + +Then change the configuration in the newly created `config.php`: + +- `$MATOMO_URL` should contain the URL to your Matomo server +- `$PROXY_URL` should contain the URL to the tracker-proxy server +- `$TOKEN_AUTH` should contain the `token_auth` + +To update later, run the same `curl … | tar xz` command again in the same directory. Your `config.php` is not part of the archive and is therefore left untouched. Note that extracting over an existing installation only adds and overwrites files, it never deletes them: to be sure you end up with exactly the current set of files, extract into an empty directory instead and move your `config.php` over. + +Be aware that with this method, `matomo.php` and other files are in a `matomo/` subdirectory. Keep that in mind when applying the instructions for the next step. Extract the archive directly into your website root directory instead if you prefer the proxy at `http://{site_to_be_tracked}/matomo.php`. + #### Manual download of `matomo.php` - download [`matomo.php`](https://raw.githubusercontent.com/matomo-org/tracker-proxy/master/matomo.php), download [`piwik.php`](https://raw.githubusercontent.com/matomo-org/tracker-proxy/master/piwik.php), [`proxy.php`](https://raw.githubusercontent.com/matomo-org/tracker-proxy/master/proxy.php), [`matomo-proxy.php`](https://raw.githubusercontent.com/matomo-org/tracker-proxy/master/matomo-proxy.php) & if you are using the Heatmaps and Session recordings plugin also download [`plugins/HeatmapSessionRecording/configs.php`](https://raw.githubusercontent.com/matomo-org/tracker-proxy/master/plugins/HeatmapSessionRecording/configs.php) @@ -47,19 +73,6 @@ You need to install the proxy on the server where your websites are hosted. You - `$PROXY_URL` should contain the URL to the tracker-proxy server - `$TOKEN_AUTH` should contain the `token_auth` -#### With git - -- clone the repository: `git clone https://github.com/matomo-org/tracker-proxy.git matomo` into your website root directory (for example at `http://{site_to_be_tracked}/matomo/matomo.php`) -- copy the configuration template: `cp config.php.example config.php` -- change the configuration in the newly created `config.php`: - - `$MATOMO_URL` should contain the URL to your Matomo server - - `$PROXY_URL` should contain the URL to the tracker-proxy server - - `$TOKEN_AUTH` should contain the `token_auth` - -By using git you will later be able to update by simply running `git pull`. - -Be aware that with this method, `matomo.php` and other files are in a `matomo/` subdirectory. Keep that in mind when applying the instructions for the next step. - ### 3. Use the proxy in the Javascript tracker The proxy file (`http://{site_to_be_tracked}/matomo.php`) will be called by the Matomo Javascript tracker instead of calling directly the (secret) Matomo server (`http://your-matomo-domain.example.org/matomo/`). @@ -85,7 +98,7 @@ To achieve this, change the Matomo Javascript Code that is in the footer of your What has changed in this code snippet compared to the normal Matomo code? - any reference(s) to the secret Matomo URL are now replaced by your website URL (the proxy). - - `matomo.js` becomes `matomo.php` (or `matomo/matomo.php` if you used the *git* method): matomo.php is the proxy script + - `matomo.js` becomes `matomo.php` (or `matomo/matomo.php` if you installed the proxy into a `matomo/` subdirectory): matomo.php is the proxy script - make sure to replace `tracked-site-id-here` with your idsite - if the `