Comprehensive Engineering Guide to Deploying Matomo Analytics via Docker

The deployment of Matomo, formerly known as Piwik, within a containerized environment represents a strategic shift toward data sovereignty and operational flexibility. As a leading open-source analytics platform, Matomo provides an alternative to proprietary trackers by offering 100% data ownership, rigorous user privacy protection, and user-centric insights. The transition to Docker allows administrators to encapsulate the entire application stack—consisting of a web server, a PHP runtime, and a SQL database—into portable units. This architectural approach eliminates the "it works on my machine" syndrome and streamlines the deployment pipeline across development, staging, and production environments. By leveraging Docker, organizations can ensure that their analytics infrastructure is customizable and extensible, allowing for the addition of plugins and custom configurations without risking the stability of the underlying host operating system.

Fundamental Prerequisites and Docker Validation

Before initiating the deployment of Matomo, the host environment must be properly prepared. The primary requirement is the installation of the Docker Engine and the Docker Compose plugin. These tools provide the runtime environment necessary to execute the Matomo image and the orchestration capabilities required to manage multi-container applications.

To verify if Docker is already present on the system, the following command must be executed in the terminal:

docker -v

If the system returns a version number, the environment is ready. However, if the command is not found, the user must install Docker according to the specific requirements of their operating system (Linux, macOS, or Windows). The installation of Docker is the technical foundation for this process; without it, the containerization of the PHP-based Matomo application and the MariaDB database cannot occur. The impact of missing this step is a total failure of the deployment pipeline, as the docker run and docker compose commands will be unrecognized by the shell.

Deployment Strategies via Docker Compose

Docker Compose is the recommended method for deploying Matomo because it allows the definition of the entire application stack in a single YAML file. This file acts as a blueprint for the infrastructure, ensuring that the web server, database, and language runtime are networked correctly.

The docker-compose.yml file must be created within a dedicated directory named matomo. This file contains the essential declarations for the following components:

• A web server, specifically apache2, to handle HTTP requests.
• A SQL database, utilizing mariadb, for persistent storage of analytics data.
• A programming language environment, utilizing php, to execute the Matomo source code.

Once the configuration file is finalized, the deployment is triggered using the following command:

docker compose up

This command initiates the pulling of the specified images from the registry and starts the services. After a few minutes of initialization, the application becomes accessible via the browser at http://localhost:8080.

Direct Container Execution and Persistence

For scenarios where a full Compose file is not desired, or for rapid prototyping, Matomo can be launched using the docker run command. This method requires a pre-existing MySQL or MariaDB database container to be active, as Matomo cannot function without a relational database for its data storage.

To start a basic Matomo container and link it to a database container named some-mysql, the following command is used:

docker run -d --link some-mysql:db matomo

However, standard containers are ephemeral, meaning all data is lost when the container is deleted. To ensure data persistence, a Docker volume must be mapped from the host machine to the container's internal storage path. This is critical for maintaining the analytics database and configuration files over time. The command to implement persistence and port mapping is:

docker run -d -p 8080:80 --link some-mysql:db -v matomo:/var/www/html matomo

In this command, -p 8080:80 maps the host's port 8080 to the container's port 80, and -v matomo:/var/www/html creates a named volume to preserve the application's state. Once the container is operational, the user is directed to the configuration wizard page to complete the software setup.

Analysis of Available Docker Images and Tags

The Matomo ecosystem provides various image tags on Docker Hub to cater to different architectural needs. Choosing the correct tag affects the image size, the included web server, and the underlying operating system.

The fpm-alpine images are particularly valuable for users seeking a reduced footprint, as they are significantly smaller (approximately 58MB) compared to the standard Apache images. This allows for faster deployment and lower resource consumption on the host.

Advanced Configuration using Bitnami Images

Bitnami provides a highly optimized version of the Matomo image that allows for extensive configuration via environment variables. This removes the need to manually edit files inside the container and allows for "Infrastructure as Code" practices.

Environment Variable Customization

Users can adjust the instance configuration by passing variables during the docker run command or within the docker-compose.yml file. For instance, to set a specific password for the application, the following variable is used:

MATOMO_PASSWORD=my_password

In a docker run command, this is implemented using the -e flag:

docker run -d -e MATOMO_PASSWORD=my_password -p 80:80 --name matomo -v /your/local/path/bitnami/matomo:/bitnami --net=matomo_network bitnami/matomo

Reverse Proxy and SSL Configuration

For production environments where Matomo is placed behind a reverse proxy (such as Nginx or HAProxy), specific environment variables must be set to ensure that SSL and client IP addresses are handled correctly. This prevents the application from redirecting incorrectly or masking the actual visitor IP.

The required variables are:

• MATOMO_PROXY_CLIENT_HEADER=HTTP_X_FORWARDED_FOR
• MATOMO_ENABLE_FORCE_SSL=yes
• MATOMO_ENABLE_ASSUME_SECURE_PROTOCOL=yes

A full execution command for a reverse proxy setup is:

docker run -d --name matomo -p 80:80 -p 443:443 --net matomo_network -e MARIADB_HOST=mariadb -e MARIADB_PORT_NUMBER=3306 -e MATOMO_DATABASE_USER=bn_matomo -e MATOMO_DATABASE_NAME=bitnami_matomo -e MATOMO_PROXY_CLIENT_HEADER=HTTP_X_FORWARDED_FOR -e MATOMO_ENABLE_FORCE_SSL=yes -e MATOMO_ENABLE_ASSUME_SECURE_PROTOCOL=yes -v /your/local/path/bitnami/matomo:/bitnami bitnami/matomo:latest

Bitnami-Specific Orchestration and Networking

When deploying using Bitnami images, a dedicated Docker network is required to facilitate communication between the Matomo application container and the MariaDB database container.

First, the network must be created:

docker network create matomo_network

Next, the MariaDB container is launched. It is essential to give the container a specific name (e.g., --name mariadb) because Matomo uses this name to resolve the database host.

docker run -d --name mariadb -e ALLOW_EMPTY_PASSWORD=yes -e MARIADB_USER=bn_matomo -e MARIADB_DATABASE=bitnami_matomo --net matomo_network --volume /path/to/mariadb-persistence:/bitnami bitnami/mariadb:latest

Following the database setup, the Matomo container is launched:

docker run -d --name matomo -p 80:80 -p 443:443 -e ALLOW_EMPTY_PASSWORD=yes -e MATOMO_DATABASE_USER=bn_matomo -e MATOMO_DATABASE_NAME=bitnami_matomo --net matomo_network --volume /path/to/matomo-persistence:/bitnami bitnami/matomo:latest

Internal Configuration and Troubleshooting

In some deployment scenarios, specifically when using non-standard ports like 8080, the application may trigger security or access errors because the trusted_hosts configuration does not match the access URL. This requires manual intervention inside the container.

Modifying the Trusted Hosts

To resolve this, the administrator must first identify the container ID:

docker ps

Once the ID (e.g., 670e5185880a) is identified, the administrator enters the container's terminal:

docker exec -it 670e5185880a /bin/bash

Since the container typically lacks a text editor, nano must be installed:

apt update && apt install nano

The configuration file is then edited:

nano config/config.ini.php

The line trusted_hosts[] = "localhost" must be modified to:

trusted_hosts[] = "localhost:8080"

After saving the file with Ctrl-X and Enter, the Matomo login page can be reloaded, and the sign-in form will be accessible.

Data Management: Backups and Restoration

Ensuring the integrity of analytics data is paramount. Because Matomo stores its data in both the database and the filesystem, a complete backup strategy must encompass both.

The Backup Process

To create a backup, the Matomo container must first be stopped to ensure data consistency:

docker stop matomo

Alternatively, if using Compose:

docker-compose stop matomo

The backup is performed using a temporary busybox container. This container mounts the existing Matomo volumes and copies the data to a backup directory on the host:

docker run --rm -v /path/to/matomo-backups:/backups --volumes-from matomo busybox cp -a /bitnami/matomo /backups/latest

This method ensures that the entire /bitnami/matomo directory, including configuration and logs, is preserved.

The Restoration Process

Restoring a backup is achieved by mounting the backup volumes back into the containers during the docker run command. For the MariaDB container, the volume mapping is adjusted to point to the restored data path:

--volume /path/to/mariadb-persistence:/bitnami/mariadb

Database Connection Details

During the Matomo installation wizard, the system will request database connection details. If using the provided Docker Compose or Bitnami configurations, these details are derived from the environment variables:

• Database Server: This is typically the IP address of the database server or the container name (e.g., mariadb or some-mysql) if using a Docker network.
• Database Password: This is defined by the MYSQL_ROOT_PASSWORD variable (e.g., password123* in some examples) or handled via ALLOW_EMPTY_PASSWORD=yes.

Conclusion

The deployment of Matomo via Docker transforms a complex installation process into a repeatable, scalable engineering task. By utilizing Docker Compose, administrators can orchestrate the interplay between Apache, PHP, and MariaDB with precision. The choice between standard images and Bitnami images allows users to balance the need for simplicity with the need for advanced configuration via environment variables. Whether utilizing lightweight Alpine-based images for resource efficiency or implementing complex reverse proxy settings for production-grade security, Docker provides the necessary isolation and portability. The ability to maintain persistent data through volumes and execute precise backups via auxiliary containers ensures that the 100% data ownership promised by Matomo is technically realized and securely maintained.

Sources

1. Data Marketing School - Install Matomo on Docker with Docker Compose
2. Matomo Docker GitHub
3. Docker Hub - Matomo Tags
4. Matomo FAQ - How to install
5. Docker Hub - Bitnami Matomo