Self-Hosted Matomo with Docker: Privacy-Friendly Analytics, Tracking, and Maintenance
MatomoWeb AnalyticsPrivacyDockerGDPROpen Source

Self-Hosted Matomo with Docker: Privacy-Friendly Analytics, Tracking, and Maintenance

sselfhosting.cloud Editorial Team
2026-11-15
8 min read

Deploy Matomo with Docker, configure privacy-aware tracking, automate report archiving, and maintain reliable backups and retention.

Self-hosting Matomo with Docker gives you control over where analytics data is stored, how long it is retained, and which tracking features are enabled. This guide covers a practical deployment pattern with MariaDB, a reverse proxy, HTTPS, consent-aware tracking, scheduled report archiving, permissions, backups, and a recurring maintenance workflow.

Overview

Matomo is an open-source analytics platform that can serve as a privacy-focused alternative to hosted analytics services. A self-hosted installation is useful when your team needs direct access to raw analytics data, wants to keep application data on infrastructure it controls, or needs more flexibility around retention and user access.

That control also creates operational responsibilities. You must secure the server, protect the database, configure HTTPS correctly, decide whether consent is required for each tracking method, and ensure that scheduled archive jobs run reliably. A dashboard that loads is not necessarily a healthy analytics installation: reports can become incomplete when cron jobs fail, tracking can be duplicated by a tag manager, and historical data can grow until backups and storage become difficult to manage.

The deployment below assumes a Linux VPS or home server with Docker Compose, a DNS record such as analytics.example.com, and an existing reverse proxy. You can use Traefik or Nginx Proxy Manager; the important requirements are that the proxy forwards HTTPS traffic to Matomo, preserves the original host and protocol headers, and does not expose the database publicly. See the Traefik vs Nginx Proxy Manager guide if you are still choosing a proxy.

  • Matomo: the web application and tracking endpoint.
  • MariaDB: the database for configuration, visits, reports, and metadata.
  • Reverse proxy: public HTTPS termination and hostname routing.
  • Persistent storage: named volumes or dedicated directories for both services.
  • Cron: a scheduled archive process that converts collected visit data into reports.

Deploy Matomo with Docker Compose

Create a dedicated directory and restrict access to the environment file. Do not reuse a database password from another application, and do not commit secrets to a public Git repository.

mkdir -p /opt/matomo
cd /opt/matomo
umask 077
touch .env

Put database credentials and the public hostname in .env. Pin image tags to versions you have tested instead of relying on latest; the exact compatible Matomo, PHP, and MariaDB combinations should be checked against the release documentation before an upgrade.

MATOMO_HOST=analytics.example.com
MYSQL_DATABASE=matomo
MYSQL_USER=matomo
MYSQL_PASSWORD=replace-with-a-long-random-value
MYSQL_ROOT_PASSWORD=replace-with-a-different-long-random-value

MATOMO_IMAGE=matomo:tested-version
MARIADB_IMAGE=mariadb:tested-version

Use this as a starting Compose file. The proxy can connect to the matomo service over a shared Docker network, or you can publish the web port only to the local host and proxy to that address.

services:
  db:
    image: ${MARIADB_IMAGE}
    restart: unless-stopped
    command: --max-allowed-packet=64M
    environment:
      MARIADB_DATABASE: ${MYSQL_DATABASE}
      MARIADB_USER: ${MYSQL_USER}
      MARIADB_PASSWORD: ${MYSQL_PASSWORD}
      MARIADB_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
    volumes:
      - db_data:/var/lib/mysql
    networks:
      - matomo_internal

  matomo:
    image: ${MATOMO_IMAGE}
    restart: unless-stopped
    depends_on:
      - db
    environment:
      MATOMO_DATABASE_HOST: db
      MATOMO_DATABASE_ADAPTER: mysql
      MATOMO_DATABASE_TABLES_PREFIX: matomo_
      MATOMO_DATABASE_DBNAME: ${MYSQL_DATABASE}
      MATOMO_DATABASE_USERNAME: ${MYSQL_USER}
      MATOMO_DATABASE_PASSWORD: ${MYSQL_PASSWORD}
    volumes:
      - matomo_data:/var/www/html
    ports:
      - "127.0.0.1:8080:80"
    networks:
      - matomo_internal

volumes:
  db_data:
  matomo_data:

networks:
  matomo_internal:

Start the stack with docker compose up -d, then open the hostname through your reverse proxy. During the web installer, confirm the database host is db, use the credentials from .env, and create an administrator account with a unique password. After installation, verify that the Matomo URL uses HTTPS and that the application generates the correct canonical URL.

For production use, keep the database on an internal Docker network and expose only the web application through the proxy. Set the proxy's WebSocket and forwarding behavior according to its documentation, pass the original HTTPS scheme, and avoid terminating TLS at multiple layers unless you have a clear reason. A Cloudflare Tunnel can be another publication method when opening inbound ports is undesirable, but it still requires careful hostname, access, and header configuration.

Tracking methods and privacy choices

Matomo supports more than one way to collect data. Choose one primary method for each site and document the decision. Running the JavaScript tracker and server log import for the same traffic without exclusions can produce duplicate visits.

MethodBest fitOperational and privacy considerations
JavaScript trackingWebsites needing page views, events, campaigns, and browser contextEasy to install, but consent behavior, cookie settings, browser restrictions, and ad blockers affect collection.
Server log importSites where web server logs are already retained and browser scripts are undesirableRequires correctly formatted logs and an import schedule. It may provide less client-side context and must be assessed against your retention and access rules.
Measurement APIBackend events, applications, and custom integrationsRequires authentication and input validation. Keep API tokens out of client-side code and review event naming before deployment.

Privacy configuration checklist

  • Document the purpose of analytics for every tracked site and decide whether consent is required in the jurisdictions relevant to your audience.
  • Configure a consent manager or consent mode that matches your legal review. Do not treat a technical setting as a complete compliance decision.
  • Enable IP anonymization or other visitor-data minimization features when appropriate for your use case.
  • Review cookie use, campaign parameters, user IDs, custom dimensions, and recorded URLs for unnecessary personal information.
  • Disable User ID tracking unless there is a documented need and a clear rule preventing direct identifiers from entering analytics.
  • Limit administrator and analyst permissions. Give site owners access only to the sites and reports they need.
  • Set a report and raw-data retention period that your organization can justify and maintain.

Analytics data can become personal data through combinations of fields even when names and email addresses are absent. Keep tracking configuration, consent records, access logs, and retention decisions documented. If your environment includes other sensitive services, separate them by hostname, credentials, and network policy. The site's Docker Compose stack planning guide provides a useful approach to organizing those boundaries.

Cron archiving, backups, and permissions

Matomo can collect visits before reports are fully processed. Scheduled archiving is therefore a core reliability task, not an optional optimization. Run the archive command from a host cron job, a scheduler container, or another trusted automation system. A simple host-level example is:

*/5 * * * * cd /opt/matomo && docker compose exec -T matomo php /var/www/html/console core:archive >> /var/log/matomo-archive.log 2>&1

The exact schedule depends on traffic volume and how quickly reports need to become available. Avoid overlapping archive processes. Check the Matomo system report and container logs after enabling the job, then monitor the archive log for database connection failures, permission errors, or unusually long runtimes.

Back up both the database and the Matomo volume, but treat them differently. A database dump is the primary recovery artifact for analytics records; the application volume may contain configuration, plugins, and generated files that should also be preserved or reproducibly restored. Store at least one backup outside the server, encrypt it where appropriate, and test restoration into an isolated environment. The guidance in self-hosted database operations for Docker apps is also relevant to backup verification and upgrade planning, even when your Matomo deployment uses MariaDB.

Do not make the Matomo container run with broader host access than it needs. Keep Docker administration limited to trusted operators, protect the reverse-proxy dashboard, and use a firewall to expose only required services. Add uptime checks for the public hostname and disk-space alerts for the database and backup locations. A monitoring stack such as Uptime Kuma, Prometheus, and Grafana can provide the operational view described in the self-hosted monitoring guide.

What to track each month

A recurring review turns self-hosted analytics from a set-and-forget application into a managed service. Record the following checkpoints in an operations document:

  • Collection: confirm recent visits, page views, events, campaign data, and conversions appear as expected.
  • Archive health: verify the last successful archive time and investigate gaps rather than assuming low traffic is the explanation.
  • Infrastructure: inspect CPU, memory, database size, volume capacity, container restarts, and error logs.
  • Security: review administrator accounts, unused users, plugin changes, exposed ports, and recent authentication activity.
  • Backups: confirm recent dumps exist, are readable, and can be restored. A backup timestamp alone is not a recovery test.
  • Privacy: sample URLs, events, custom dimensions, and user settings for accidental identifiers or unexpected collection.
  • Retention: check whether automatic deletion is working and whether storage growth matches the selected policy.

At least quarterly, review the image tags and Matomo release notes before upgrading. Test upgrades on a copy or staging instance when possible, take a fresh backup, record the current versions, and validate login, tracking, report generation, cron archiving, exports, and reverse-proxy behavior afterward. Avoid changing Matomo, PHP, the database, and the proxy simultaneously unless you have a tested rollback plan.

How to interpret changes

A sudden change in analytics is not automatically a change in audience behavior. First separate measurement changes from traffic changes. Compare the timing of the anomaly with a tag deployment, consent-banner change, browser update, proxy change, site redesign, campaign launch, or archive-job failure.

If visits fall while server access logs remain stable, inspect the JavaScript tag, consent state, content-security policy, cache behavior, and browser console errors. If both analytics and server logs fall, investigate the site, DNS, hosting, or campaign source. If reports show a spike in one page or event, check duplicate tags, retry behavior, API loops, and bot traffic before drawing a product conclusion.

Keep a short change log with deployment dates, tracking changes, consent configuration, new sites, deleted sites, and report-retention adjustments. This makes comparisons more reliable and helps distinguish a real trend from a measurement artifact.

When to revisit and what to do next

Revisit this Matomo deployment monthly for health, privacy, retention, and backup checks; revisit it quarterly for version and configuration review; and revisit it immediately after adding a site, changing a consent system, modifying the reverse proxy, or changing tracking methods. Browser behavior, Matomo APIs, supported database combinations, and privacy requirements can change, so verify the relevant documentation before a major upgrade.

  1. Choose a hostname and create its DNS record.
  2. Prepare a locked-down Compose directory and unique database credentials.
  3. Deploy pinned, tested Matomo and MariaDB images.
  4. Configure HTTPS through your reverse proxy and complete the installer.
  5. Select one tracking method per site and document consent and minimization settings.
  6. Schedule core:archive and confirm it completes successfully.
  7. Set permissions, retention, backups, monitoring, and a restoration test.
  8. Record the deployed versions and add the monthly checklist to your operations calendar.

With those controls in place, self-hosted Matomo becomes more than a Docker container: it is a maintainable analytics service with a defined data lifecycle, a recovery path, and clear checkpoints for future changes.

Related Topics

#Matomo#Web Analytics#Privacy#Docker#GDPR#Open Source
s

selfhosting.cloud Editorial Team

Technical Editor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.