Skip to content
Klutch.sh Docs

Deploying a Matomo App

Introduction

Matomo (formerly Piwik) is an open-source web analytics platform that runs on PHP with a MySQL-compatible database. Deploying Matomo with a Dockerfile on Klutch.sh gives you reproducible builds, managed secrets, and persistent storage for config and session files—all from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, and sample tracking usage.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your Matomo setup and Dockerfile (GitHub is the only supported git source)
  • A MySQL or MariaDB instance (deploy as a Klutch.sh TCP app on port 8000 and connect on 3306)
  • Domain ready for your Matomo instance
  • Optional SMTP credentials for email reports

For onboarding, see the Quick Start.

Architecture and ports

  • Matomo web runs on PHP/Apache; set the internal container port to 8080 and choose HTTP traffic.
  • Database runs separately (MySQL/MariaDB) on TCP, accessible via port 8000 from outside; use 3306 internally.
  • Persistent storage is required for configuration and tmp/cache data.

Repository layout

matomo/
├── Dockerfile                # Must be at repo root for auto-detection
├── config/                   # Matomo config (persist)
├── tmp/                      # Cache/sessions (persist)
├── plugins/                  # Custom plugins/themes
└── README.md

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Validate locally before pushing to GitHub:

Terminal window
docker build -t matomo-local .
docker run -p 8080:8080 --env-file .env matomo-local

Dockerfile for Matomo (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM matomo:4-apache


# Ensure Apache listens on 8080 inside the container
ENV APACHE_HTTP_PORT_NUMBER=8080


WORKDIR /var/www/html


# Copy custom plugins/themes if present
COPY plugins ./plugins


# Set correct permissions for persistent dirs
RUN mkdir -p ./config ./tmp && chown -R www-data:www-data ./config ./tmp ./plugins


EXPOSE 8080
CMD ["apache2-foreground"]

Notes:

  • Add additional PHP extensions via docker-php-ext-install if your plugins require them.
  • Keep config/ and tmp/ writable; mount them as volumes.

Environment variables (Klutch.sh)

Set these in Klutch.sh before deploying:

  • MATOMO_DATABASE_HOST=<db-host>
  • MATOMO_DATABASE_USERNAME=<db-user>
  • MATOMO_DATABASE_PASSWORD=<db-password>
  • MATOMO_DATABASE_DBNAME=<db-name>
  • MATOMO_DATABASE_ADAPTER=PDO_MYSQL
  • MATOMO_DATABASE_TABLES_PREFIX=matomo_ (optional)
  • MATOMO_TRUSTED_HOSTS=example-app.klutch.sh
  • APACHE_HTTP_PORT_NUMBER=8080
  • Optional SMTP: MATOMO_MAIL_FROM_ADDRESS, MATOMO_MAIL_FROM_NAME, MATOMO_MAIL_HOST, MATOMO_MAIL_PORT, MATOMO_MAIL_USERNAME, MATOMO_MAIL_PASSWORD, MATOMO_MAIL_ENCRYPTION

If you deploy without the Dockerfile and need Nixpacks overrides (PHP):

  • NIXPACKS_PHP_VERSION=8.2
  • NIXPACKS_START_CMD=apache2-foreground

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required):

  • /var/www/html/config — configuration, secrets, and installation state.
  • /var/www/html/tmp — cache and sessions.

Ensure these directories are writable.

Deploy Matomo on Klutch.sh (Dockerfile workflow)

  1. Push your repository—with the Dockerfile at the root—to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Select HTTP traffic and set the internal port to 8080.
  4. Add the environment variables above, including database and SMTP settings.
  5. Attach persistent volumes for /var/www/html/config and /var/www/html/tmp with sizes that match your data and cache needs.
  6. Deploy. Complete the web-based installer at https://example-app.klutch.sh and connect it to your database.

Sample tracking snippet

Add this JavaScript to a site you want to track (replace the URL with your Matomo domain):

<script>
  var _paq = window._paq = window._paq || [];
  _paq.push(['trackPageView']);
  _paq.push(['enableLinkTracking']);
  (function() {
    var u="https://example-app.klutch.sh/";
    _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>

Health checks and production tips

  • Add an HTTP probe to / or /matomo.php to confirm availability.
  • Enforce HTTPS at the edge; forward traffic internally to port 8080.
  • Keep Matomo and plugins updated; test upgrades in a staging branch.
  • Monitor database connections and storage; resize volumes before they fill.
  • Store secrets only in Klutch.sh and rotate them regularly.
  • If you enable GeoIP, ensure the required DB files are downloaded at build or startup.

Matomo on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage, and flexible HTTP/TCP routing. With the Dockerfile at the repo root, port 8080 configured, and a reliable database connection, you can ship privacy-focused analytics without extra YAML or workflow overhead.