About
Matomo (formerly Piwik) Docker image based on Alpine Linux and Nginx.
If you are interested, check out my other Docker images!
- Features
- Build locally
- Image
- Environment variables
- Volumes
- Ports
- Usage
- Upgrade
- Notes
- How can I help?
- License
Features
- Run as non-root user
- Multi-platform image
- Config, plugins and user preferences in the same folder
- Unifont for languages using unicode characters
- Cron tasks to archive Matomo reports as a "sidecar" container
- Ability to pass additional options during cron archive
- Plugins and config are kept across upgrades of this image
- OPCache enabled to store precompiled script bytecode in shared memory
- Redis enabled and ready to enhance server performance
- s6-overlay as process supervisor
- Traefik Docker image as reverse proxy and creation/renewal of Let's Encrypt certificates
- msmtpd SMTP relay image to send emails
- Redis Docker image ready to use as Redis cache or QueuedTracking plugin for better scalability
- MariaDB Docker image as database instance
- geoip-updater Docker image to download MaxMind's GeoIP2 databases on a time-based schedule for geolocation
- Cron jobs as a "sidecar" container
Build locally
git clone https://github.com/crazy-max/docker-matomo.git
cd docker-matomo
# Build image and output to docker (default)
docker buildx bake
# Build multi-platform image
docker buildx bake image-all
Image
Registry | Image |
---|---|
Docker Hub | crazymax/matomo |
GitHub Container Registry | ghcr.io/crazy-max/matomo |
Following platforms for this image are available:
$ docker run --rm mplatform/mquery crazymax/matomo:latest
Image: crazymax/matomo:latest
* Manifest List: Yes
* Supported platforms:
- linux/amd64
- linux/arm/v6
- linux/arm64
- linux/386
- linux/ppc64le
- linux/s390x
Environment variables
TZ
: The timezone assigned to the container (defaultUTC
)PUID
: Matomo user id (default1000
)PGID
: Matomo group id (default1000
)MEMORY_LIMIT
: PHP memory limit (default256M
)UPLOAD_MAX_SIZE
: Upload max size (default16M
)CLEAR_ENV
: Clear environment in FPM workers (defaultyes
)OPCACHE_MEM_SIZE
: PHP OpCache memory consumption (default128
)LISTEN_IPV6
: Enable IPv6 for Nginx (defaulttrue
)REAL_IP_FROM
: Trusted addresses that are known to send correct replacement addresses (default0.0.0.0/32
)REAL_IP_HEADER
: Request header field whose value will be used to replace the client address (defaultX-Forwarded-For
)LOG_IP_VAR
: Use another variable to retrieve the remote IP address for access log_format on Nginx. (defaultremote_addr
)LOG_LEVEL
: Log level of Matomo UI (defaultWARN
)SHORTCODE_DOMAIN
: Domain that you use for ShortcodeTracker plugin (defaultinvalid
)
The following environment variables are only used if you run the container as "sidecar" mode:
SIDECAR_CRON
: Set to1
to enable sidecar cron mode (default0
)ARCHIVE_OPTIONS
: Pass additional options during cron archiveCRON_ARCHIVE
: Periodically execute Matomo archive (disabled if empty ; ex0 * * * *
)
Volumes
/data
: Contains GeoIP2 databases, configuration, installed plugins (not core ones), tmp and user folders to store your custom logo
β οΈ Note that the volume should be owned by the user/group with the specifiedPUID
andPGID
. If you don't give the volume correct permissions, the container may not start.
Ports
8000
: HTTP port
Usage
Docker Compose
Docker compose is the recommended way to run this image. Copy the content of folder examples/compose
in /var/matomo/
on your host for example. Edit the compose and env files with your preferences and run the following
commands:
touch acme.json
chmod 600 acme.json
docker-compose up -d
docker-compose logs -f
Swarm
Deploy this image in your Swarm cluster. Detailed instructions can be found here.
Kubernetes
Deploy this image in your kubernetes cluster. Detailed instructions can be found here.
Command line
You can also use the following minimal command:
docker run -d -p 8000:8000 --name matomo \
-v $(pwd)/data:/data \
crazymax/matomo:latest
β οΈ You will need to have your own database server to connect to as this only runs Matomo.
Upgrade
You can upgrade Matomo automatically through the UI, it works well. But I recommend to recreate the container whenever I push an update:
docker-compose pull
docker-compose up -d
Notes
Console command
If you want to use the console
command to perform common server operations, type:
docker-compose exec matomo console
Email server settings
You can use our SMTP relay msmtpd
service published on port 2500
and declared in our
docker-compose.yml
:
Sticky sessions
On a HA environment, enable backend sticky sessions on your load balancer.
Cron
If you want to enable the cron job, you have to run a "sidecar" container like in the docker-compose file or run a simple container like this:
docker run -d --name matomo_cron \
--env-file $(pwd)/matomo.env \
--no-healthcheck \
-e "SIDECAR_CRON=1" \
-e "CRON_ARCHIVE=0 * * * *" \
-e "ARCHIVE_OPTIONS=--concurrent-requests-per-website=3" \
-v $(pwd)/data:/data \
crazymax/matomo:latest
Then if you have enabled CRON_ARCHIVE
to automatically archive the reports, you have to disable Matomo archiving
to trigger from the browser. Go to System > General settings:
GeoIP2
This image already uses GeoIP2 databases of MaxMind with their PHP extension and are updated with geoip-updater. You just have to install and activate the GeoIP 2 plugin.
Also make sure to select DBIP / GeoIP 2 (Php) in System > Geolocation:
Behind a reverse proxy?
If you are running Matomo behind a reverse proxy, add this to your config.ini.php:
[General]
assume_secure_protocol = 1 # 0=http 1=https
proxy_client_headers[] = HTTP_X_FORWARDED_FOR
proxy_client_headers[] = HTTP_X_REAL_IP
proxy_host_headers[] = HTTP_X_FORWARDED_HOST
Redis cache
To use Redis as a cache (useful if your Matomo environment consists of multiple servers), add this to your config.ini.php:
[Cache]
backend = chained
[ChainedCache]
backends[] = array
backends[] = redis
[RedisCache]
host = "redis" # Docker service name for Redis
port = 6379
timeout = 0.0
password = ""
database = 14
In case you are using queued tracking: Make sure to configure a different database! Otherwise queued requests will be flushed.
Plugins
If you are on a HA environment, there is no need to set
multi_server_environment = 1
in your config.
How can I help?
All kinds of contributions are welcome
Thanks again for your support, it is much appreciated!
License
MIT. See LICENSE
for more details.