What are we building?

By the end, Matomo 5.12 runs in Docker behind your Traefik reverse proxy, reachable under your own (sub)domain with a valid HTTPS certificate. As the database, MariaDB 11.4 comes along – both in one compose.yaml. You get a full-featured analytics dashboard that evaluates visitor numbers, origin, devices and popular pages – the data lives exclusively on your server.

The real gain over Google Analytics is privacy: we take control of IP anonymization and configure Matomo so it works without cookies. That’s the technical basis for being able, in many cases, to do without an annoying consent banner. Matomo is the full package – if all you want to know is which pages get how many hits, the much leaner HitKeep will do as well.

Prerequisites

• A hardened server with Debian 13 and a sudo user
• Docker & Docker Compose installed
• A running Traefik reverse proxy with the external network proxy and the certificate resolver le – Matomo hooks in there
• A (sub)domain whose A/AAAA record points to your server, e.g. stats.YOUR_DOMAIN
• A working backup strategy with Restic – analytics data accumulates over years, you don’t want to lose it

Matomo is frugal: for a small to medium website, the VPS 1000 is plenty. Only with very high traffic or when many other services run alongside is it worth looking at more RAM – our server calculator helps with the assessment.

Step by step

Step 1: Create the project folder and check the network

We create a dedicated folder for Matomo under /opt – this keeps every service cleanly separated:

mkdir -p /opt/matomo && cd /opt/matomo

Matomo has to go into the same Docker network as Traefik so the proxy can reach the container. Check that the proxy network from the Traefik tutorial exists:

docker network ls | grep proxy

You should see a line with proxy. If not, set up Traefik first – without the proxy, Matomo won’t get a certificate.

Step 2: Move passwords into a .env

The database passwords do not belong in the compose.yaml, but in a separate .env. We have openssl generate them randomly:

{
  echo "DB_PASSWORD=$(openssl rand -hex 16)"
  echo "DB_ROOT_PASSWORD=$(openssl rand -hex 16)"
} > .env
chmod 600 .env

chmod 600 ensures only root can read the file. Take a look inside once so you know the values:

cat .env

DB_PASSWORD=b51024e3f9a7c8d1e2f3a4b5c6d7e8f9
DB_ROOT_PASSWORD=1a2b3c4d5e6f70819a0b1c2d3e4f5061

Step 3: Write the compose.yaml

Create the file /opt/matomo/compose.yaml with the following content. In the Traefik label, replace stats.YOUR_DOMAIN with your real (sub)domain:

services:
  db:
    image: mariadb:11.4
    container_name: matomo-db
    command: --max-allowed-packet=64MB
    environment:
      MARIADB_DATABASE: matomo
      MARIADB_USER: matomo
      MARIADB_PASSWORD: ${DB_PASSWORD}
      MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
    volumes:
      - db:/var/lib/mysql
    networks: [intern]
    restart: unless-stopped

  app:
    image: matomo:5.12-apache
    container_name: matomo
    environment:
      MATOMO_DATABASE_HOST: db
      MATOMO_DATABASE_ADAPTER: mysql
      MATOMO_DATABASE_USERNAME: matomo
      MATOMO_DATABASE_PASSWORD: ${DB_PASSWORD}
      MATOMO_DATABASE_DBNAME: matomo
    volumes:
      - app:/var/www/html
    depends_on: [db]
    networks: [proxy, intern]
    restart: unless-stopped
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.matomo.rule=Host(`stats.YOUR_DOMAIN`)"
      - "traefik.http.routers.matomo.entrypoints=websecure"
      - "traefik.http.routers.matomo.tls.certresolver=le"
      - "traefik.http.services.matomo.loadbalancer.server.port=80"

networks:
  proxy:
    external: true
  intern:
    external: false

volumes:
  db:
  app:

The most important things about this file:

• Two networks, deliberately separated. Only the app container is on the proxy network and thus reachable from outside. The database is on the internal intern network and is not addressable via Traefik – exactly right.
• The MATOMO_DATABASE_* variables pre-fill the web installer in the next step automatically. So you don’t have to type the DB data again by hand.
• max-allowed-packet=64MB is recommended by Matomo for the database, otherwise the import of large reports can abort.
• No port to the outside. Neither Matomo nor the DB publishes a host port. The only way in leads via Traefik and thus via HTTPS.

Step 4: Start the stack

docker compose up -d

On the first start, Docker downloads the images (about 310 MB of downloads, a good 1.3 GB unpacked) and creates the volumes. Then check the status:

docker compose ps

NAME        IMAGE                COMMAND                  SERVICE   CREATED          STATUS          PORTS
matomo      matomo:5.12-apache   "/entrypoint.sh apac…"   app       15 seconds ago   Up 13 seconds   80/tcp
matomo-db   mariadb:11.4         "docker-entrypoint.s…"   db        15 seconds ago   Up 14 seconds   3306/tcp

Both containers should be Up. Traefik detects the new container automatically via the labels and fetches a Let’s Encrypt certificate for your domain in the background. That usually takes only a few seconds. Check from your own machine whether Matomo responds:

curl -sI https://stats.YOUR_DOMAIN | head -1

HTTP/2 200

An HTTP/2 200 means: the certificate is in place, Traefik routes, Matomo runs. If a certificate error comes instead, give Traefik a few more seconds – see “When things go wrong”.

Step 5: Click through the web installer

Open https://stats.YOUR_DOMAIN in the browser. Matomo greets you with an eight-step setup wizard.

Click through the first steps:

1. Welcome → Next.
2. System check: Matomo checks the PHP version, extensions and write permissions. Thanks to the official image, the list stays free of errors. You’ll still see one yellow warning: Forced SSL Connection. It’s normal here and no reason to stop – Matomo’s own force_ssl option simply isn’t set yet, while delivery is HTTPS-only anyway. We clear it in step 7. → Next.
3. Set up the database: the fields are already filled in (the MATOMO_DATABASE_* variables from the compose.yaml do that). Briefly verify that the server is db, and click Next.
4. Create tables: Matomo creates its database schema. → Next.

Now you create your main administrator. Choose a username, a strong password and a real email address (security and update notices come through it).

Then you set up the first website you want to track. Besides name and URL, the website timezone is a required field: leave it on the placeholder and the form sends you back with Website timezone is not valid. It decides when a new day starts for your reports.

Step 6: Add the tracking code

In the second-to-last step, Matomo shows you the JavaScript tracking code. That’s the small snippet that belongs on every page of your website – ideally right before </head>:

<!-- Matomo -->
<script>
  var _paq = window._paq = window._paq || [];
  _paq.push(['disableCookies']);
  _paq.push(['trackPageView']);
  _paq.push(['enableLinkTracking']);
  (function() {
    var u="//stats.YOUR_DOMAIN/";
    _paq.push(['setTrackerUrl', u+'matomo.php']);
    _paq.push(['setSiteId', '1']);
    var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
    g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
  })();
</script>
<!-- End Matomo Code -->

We deliberately added the line _paq.push(['disableCookies']); (not included in the original snippet): with it, Matomo does entirely without cookies – an important building block for operation without a consent banner. If you run your website with a CMS like WordPress, there are ready-made plugins (“Matomo for WordPress”, “Connect Matomo”) that embed the snippet automatically. After the last step (“Finish”), you log in with the account you just created and land in the dashboard.

The dashboard bundles the most important reports: Visits in real-time, Visits Over Time, the Visits Overview, a Visitor Map and, under Channel Types, the origin of visitors (search engine, direct, referral). Via the menu on the left you go deeper – Visitors (devices, browsers, location), Behaviour (pages, entries and exits) and Acquisition (which channels bring visitors). Exactly the questions Google Analytics answers – only on your server.

Step 7: Check the privacy settings (the important part)

Matomo 5.12 starts out more privacy-friendly than many expect: IP anonymization is on by default. Still, walk through the page once – first, to have seen it with your own eyes, second, because there is a switch on it that really secures your cookieless tracking. Open Administration (gear) at the top right → Privacy → Anonymize data in the menu on the left.

Three knobs are decisive:

• Anonymize Visitors’ IP addresses: already set to Yes, and 2 byte(s) are masked by default – 203.0.113.45 therefore becomes 203.0.xxx.xxx (Matomo itself marks this level as Recommended). Just check that it stayed that way; with it the individual visitor is no longer identifiable.
• Force tracking without cookies: turn it on. Matomo then extends matomo.js with the matching code server-side and ignores tracking cookies on receipt as well. That still works if the original snippet without disableCookies ends up somewhere – a safety net for the very thing your consent-banner-free operation hangs on.
• “Do Not Track”: lives under Privacy → Users opt-out. Matomo now classifies the support as deprecated itself – because browsers send the signal unasked or have dropped support entirely, “we no longer recommend enabling this option”. So don’t rely on it. The dependable route is on the same page: the opt-out building block (iframe or your own form) that you embed in your privacy policy.

That leaves the switch the system check from step 5 complained about: force_ssl. It makes Matomo itself reject unencrypted access instead of relying on Traefik alone. There is no setting for it in the interface; it lives in Matomo’s config/config.ini.php inside the volume:

cd /opt/matomo
docker compose exec -u www-data app sed -i '/^\[General\]/a force_ssl = 1' config/config.ini.php

sed appends the line force_ssl = 1 right below the [General] section; -u www-data makes sure the file keeps its previous owner so Matomo can still write to it. Reload the dashboard afterwards – under Administration → Diagnostic → System Check the Forced SSL Connection warning is gone.

Step 8: Archive reports via cron

By default, Matomo computes its reports “on the fly” as soon as someone opens the dashboard. That gets slow with more traffic and is officially not recommended. Better: a cron job computes the reports regularly in the background.

For that, on the host, enter a cron job that runs the archiving command in the container every 15 minutes:

crontab -e

Add this line (adjust the domain):

*/15 * * * * cd /opt/matomo && docker compose exec -T -u www-data app ./console core:archive --url=https://stats.YOUR_DOMAIN >> /opt/matomo/archive.log 2>&1

The log deliberately lands in /opt/matomo/archive.log and not under /var/log: if your cron runs as a sudo user (not as root), a write to /var/log fails silently. In /opt/matomo you have write permissions, and you find the log right by the project.

Then switch off the old mode: Administration → General settings → Archiving settings, set “Archive reports when viewed from the browser” to No and save. This keeps the dashboard fast even with a lot of traffic – and the system check stops reporting that browser and cron archiving run side by side.

When things go wrong

Maintenance & backups

Updates are uncritical with Matomo but due regularly – a new version appears about monthly. Because we pinned the image tag to 5.12, you pull security patches within the 5.12 series like this:

cd /opt/matomo && docker compose pull && docker compose up -d

On the first call after an update, Matomo checks whether a database upgrade is needed and performs it after a click.

Backups comprise two things: the database (all visit data) and the app volume (your configuration in config/config.ini.php). Create a database dump regularly …

docker compose exec -T db sh -c 'exec mariadb-dump -u matomo -p"$MARIADB_PASSWORD" matomo' > /opt/matomo/dump.sql

… and include this dump together with the /opt/matomo folder in your Restic off-site backups. A netcup snapshot of the whole server is a good complement, but no substitute for a real off-site backup – if both are at the same provider, both are gone in a total failure.

Ongoing operation: keep an eye on disk space – with a lot of traffic the database grows. The automatic deletion of old raw data (step 7) and the archiving cron (step 8) keep Matomo lean and fast permanently. So you notice when Matomo is ever unreachable, add the instance to your Uptime Kuma monitoring – a simple HTTP check on your stats domain is enough.

And the most important operational note to finish: Matomo lives off its privacy promise. Whoever has set the service up once should not soften the anonymization and deletion settings from step 7 again – they are the reason you can do without a consent banner in the first place. After every larger update, briefly check that they’re still in place.

What are we building?

By the end, HitKeep 2.12.0 runs as a single container behind your Traefik, reachable at https://YOUR_DOMAIN. You get a dashboard with page views, visitors, time on page, referrers and devices – fed by a tiny JavaScript snippet you embed in your website. HitKeep works cookieless (no consent banner needed) and stores everything locally in an embedded DuckDB database. The image is a lean distroless image (about 71 MB) that gets by entirely without an external database – ideal for a small VPS.

Prerequisites

• A server with Debian 13 and running Docker (tested on a netcup VPS).
• A reverse proxy with Traefik that fetches TLS certificates via Let’s Encrypt. HitKeep brings no own HTTPS server – Traefik handles the encryption. This tutorial assumes the proxy network and the resolver le described there.
• A (sub)domain that points to your server (A/AAAA record). In the example we use YOUR_DOMAIN.
• The website you want to measure – HitKeep measures every page into which you embed the snippet.

Step by step

Step 1: Generate a JWT secret

HitKeep signs the login sessions with a secret key. Generate a random 32-byte value – don’t make one up, generate it:

openssl rand -hex 32

You get a 64-character hex string. Copy it – it goes into the configuration shortly. If this secret changes later, all open logins become invalid; so keep it stable and secret.

Step 2: Create the Compose file

Create a folder for the stack and change into it:

mkdir -p /opt/hitkeep && cd /opt/hitkeep

Create the file compose.yaml. Replace YOUR_DOMAIN with your real domain and YOUR_JWT_SECRET with the value from step 1:

services:
  hitkeep:
    image: pascalebeier/hitkeep:2.12.0
    container_name: hitkeep
    restart: unless-stopped
    environment:
      HITKEEP_PUBLIC_URL: https://YOUR_DOMAIN
      HITKEEP_JWT_SECRET: YOUR_JWT_SECRET
      HITKEEP_TRUSTED_PROXIES: 172.16.0.0/12
      HITKEEP_DB_PATH: /var/lib/hitkeep/data/hitkeep.db
      HITKEEP_DATA_PATH: /var/lib/hitkeep/data
      HITKEEP_ARCHIVE_PATH: /var/lib/hitkeep/archive
      HITKEEP_BACKUP_PATH: /var/lib/hitkeep/backups
    volumes:
      - hitkeep_data:/var/lib/hitkeep/data
      - hitkeep_archive:/var/lib/hitkeep/archive
      - hitkeep_backups:/var/lib/hitkeep/backups
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.hitkeep.rule=Host(`YOUR_DOMAIN`)"
      - "traefik.http.routers.hitkeep.entrypoints=websecure"
      - "traefik.http.routers.hitkeep.tls.certresolver=le"
      - "traefik.http.services.hitkeep.loadbalancer.server.port=8080"
    networks: [proxy]
volumes:
  hitkeep_data: {}
  hitkeep_archive: {}
  hitkeep_backups: {}
networks:
  proxy:
    external: true

The most important points in detail:

• HITKEEP_PUBLIC_URL is the public address under which HitKeep is reachable. The interface later builds the tracking snippet and the links from it. It must match exactly the URL under which you call HitKeep – otherwise you end up in a login loop.
• HITKEEP_TRUSTED_PROXIES is the crux behind a reverse proxy: without this value, HitKeep sees only Traefik’s internal IP as the sender of every call – then all visitors land as a single one. 172.16.0.0/12 covers the Docker networks, so HitKeep trusts Traefik’s X-Forwarded-For header and evaluates the real visitor IP.
• loadbalancer.server.port=8080 tells Traefik that HitKeep listens internally on port 8080. The container itself publishes no ports to the outside – access runs exclusively via Traefik.
• The four _PATH variables store the database, data, archive and backups under /var/lib/hitkeep/; the matching volumes ensure they survive an update or a restart.

Step 3: Start the stack and wait for TLS

Start the container:

docker compose up -d

Check the status after a few seconds:

docker compose ps

You should see the container as healthy – HitKeep brings its own healthcheck:

NAME      IMAGE                         SERVICE   STATUS                   PORTS
hitkeep   pascalebeier/hitkeep:2.12.0   hitkeep   Up 18 minutes (healthy)  7946/tcp, 8080/tcp

Traefik now fetches the Let’s Encrypt certificate for your domain in the background. Check from your own machine that the tracking script is served:

curl -sI https://YOUR_DOMAIN/hk.js

Expected output (shortened) – status 200 and a text/javascript type, aggressively cached:

HTTP/2 200
content-type: text/javascript; charset=utf-8
cache-control: public, max-age=31536000, immutable

Step 4: Create the admin account

Open https://YOUR_DOMAIN in the browser. On the very first start, HitKeep greets you with the initial setup. Create your administrator account here – name, email address and a password. Take a long passphrase or a random password generated by a password manager; this account sees all statistics and must not hang on a weak password:

Step 5: Create a website and get the tracking code

After logging in, click the plus next to Sites at the top left and create your website – as the domain, enter the domain of the site you want to measure (e.g. YOUR_WEBSITE).

Then open the site settings and switch to the Tracking tab. There you find the live tracking verifier (which waits for the first hit) and the configuration of the tracking code including the tracker host:

The code to embed consists of a single line. HitKeep needs no site ID in the snippet – the assignment happens automatically via the domain of the page on which the script runs:

<script async src="https://YOUR_DOMAIN/hk.js"></script>

Automatic event tracking (outbound clicks, downloads, form submissions) is active by default. Optionally, on the same tab, you can enable “Web Vitals” to also measure load times (LCP, INP, CLS, FCP, TTFB), or enable “Collect DNT” if you also want to count visitors with “Do Not Track” – from a privacy perspective the default (respect DNT) is the cleaner one.

Step 6: Embed the tracking code in the website

Add the snippet line from step 5 into the <head> of your website – for a static page directly into the HTML template, for a CMS into the header area or a “Custom HTML” field. Thanks to the async attribute, the script doesn’t block the page build.

Then open a page of your website in the browser. The live tracking verifier from step 5 should jump from “Waiting” to a first hit within a few seconds – that’s the confirmation that the chain website → hk.js → HitKeep is in place.

Step 7: Check the dashboard

As soon as hits trickle in, the dashboard fills up. Under Dashboard you see your website’s key figures – live visitors, page views, unique sessions, bounce rate, time on page and the traffic trend:

Further down, Latest Hits lists the individual calls with path, time, referrer and device – here you see at a glance which search engines and referrals your visitors come from:

With that your self-hosted statistics are in place: every call to your website lands directly in your own database, without a detour via third parties.

Step 8: More than just page views

For the start, page views and referrers are enough – but HitKeep can do considerably more, and you find the building blocks in the left navigation. A few that are worth it for most sites:

• Goals: define an event as a goal – e.g. the submission of a contact form or a click on “Buy”. This way you measure not only how many come, but how many do what you want.
• Funnels: chain several steps (home page → product page → cart) and see at which point visitors drop off.
• Events: besides the automatically captured events (outbound clicks, downloads, forms), you can send your own events from your frontend.
• Web Vitals: if you enable them on the tracking tab, you see real load times of your visitors (LCP, INP, CLS) instead of synthetic lab values.
• UTM: campaign parameters (utm_source, utm_medium, utm_campaign) are evaluated – handy to tell newsletter from social reach.
• Email Reports: have a summary sent to you regularly by email instead of having to look into the dashboard yourself.

A single HitKeep instance also manages any number of websites: via the plus next to Sites you create more, each with its own snippet and its own dashboard. So you don’t need a second container if you want to measure several projects.

When things go wrong

Maintenance & backups

Updates: HitKeep moves along briskly in the 2.x series – check the releases about monthly. For an update, set the new tag in the compose.yaml (replace 2.12.0 with the new version) and pull it:

docker compose pull && docker compose up -d

Because the data lives in volumes, your statistics are preserved. Deliberately pin the version to a fixed tag instead of latest, so a restart doesn’t slip you an unplanned new major version.

Backups: Your entire statistics live in an embedded DuckDB file (hitkeep.db plus the write-ahead log hitkeep.db.wal) under /var/lib/hitkeep/data. So don’t back up a single file, but the complete hitkeep_data volume regularly – cleanest with Restic. Because these files are written during operation, you back them up most consistently by briefly stopping the container (docker compose stop), backing up the volume and starting again – or by including the backup HitKeep stores under HITKEEP_BACKUP_PATH. A backup you’ve never restored is just a glimmer of hope: test the restoration once on a test system.

Cleanup: The database grows with the traffic. Keep an eye on the size of the volumes (docker system df -v) and plan for enough storage with a lot of traffic.