Matomo on AWS User Guide

Overview

This image runs Matomo, the leading open source, privacy-first web analytics platform and a fully featured self-hosted alternative to Google Analytics that keeps 100% ownership of your data on your own server. Matomo is delivered as a production LAMP application so a complete analytics platform is running within minutes of launch.

Matomo runs as a PHP 8.3 application under php-fpm, served by nginx on port 80. A MariaDB database stores every visit, action, goal and report. The Matomo application code lives under /var/www/matomo, and the analytics database lives at /var/lib/mysql, which is a dedicated, independently resizable EBS data volume that survives instance replacement. Systemd manages MariaDB, the PHP FastCGI workers and nginx, starting them on boot and restarting them on failure.

Matomo secures its dashboard with its own administrator login. On the first boot of every deployed instance a one shot service generates a fresh MariaDB password and a fresh administrator password, both unique to that instance, creates the Matomo superuser, and pins the dashboard to the instance address, so two instances launched from the same Amazon Machine Image never share credentials. The administrator password is written to /root/matomo-credentials.txt with mode 0600 so that only the root user can read it.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and port 80 for the Matomo dashboard
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Matomo. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of t3.large or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network and port 80 for the Matomo dashboard. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes a few seconds after the instance state becomes Running and the status checks pass, while the per instance database and administrator passwords are generated and the Matomo schema is created.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Matomo Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22 and 80 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=matomo}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Step 3: Connect to Your Instance

Connect over SSH using your key pair and the login user for your operating system variant.

ssh -i <key-name>.pem ubuntu@<public-ip>

Step 4: Retrieve the Administrator Password

The Matomo administrator password is unique to your instance and was generated on first boot. Read it as root:

sudo cat /root/matomo-credentials.txt

The file lists the dashboard URL, the administrator login (admin), the administrator email and the generated password. Keep this password somewhere safe.

Step 5: Sign In to the Matomo Dashboard

The Matomo dashboard is served on port 80 by nginx through php-fpm. In a browser, go to:

http://<instance-public-ip>/

Sign in as admin with the password from the credentials file. You land on the Matomo dashboard, where the Visitors overview shows the visits-over-time graph and the headline analytics sparklines.

The Behaviour reports break down page views, entry and exit pages, page titles, downloads and outlinks for every URL, with no data sampling because the data never leaves your server.

Step 6: Confirm Matomo Is Running

Over SSH, confirm the database, the PHP FastCGI workers and the nginx proxy are active and that the dashboard answers:

sudo systemctl is-active mariadb php8.3-fpm nginx
curl -s -o /dev/null -w 'matomo.php HTTP %{http_code}\n' http://127.0.0.1/matomo.php

You should see all three services reported as active and the Matomo tracking endpoint answering 200. MariaDB listens on loopback only and is never exposed publicly; only nginx on port 80 is reachable from outside the instance.

Step 7: Set Your Trusted Host or Custom Domain

Matomo rejects any request whose HTTP Host header is not in its trusted hosts list. First boot already pins your instance public IP, which is why the dashboard is reachable immediately. You can confirm the current trusted hosts at any time:

sudo grep -E 'trusted_hosts|enable_trusted_host_check' /var/www/matomo/config/config.ini.php

When you put Matomo behind a custom domain or a load balancer, add that hostname to the trusted hosts list. The simplest way is in the dashboard under Administration, then System, then General settings, where Matomo lists the trusted hostnames and lets you add your own. You can also add it from the command line with the bundled console, substituting your own hostname for analytics.example.com: sudo -u www-data php /var/www/matomo/console config:set --section=General --key='trusted_hosts[]' --value='analytics.example.com', then reload php-fpm with sudo systemctl reload php8.3-fpm so the change takes effect.

After adding a domain, point its DNS A record at the instance public IP and browse to http://analytics.example.com/.

Step 8: Add a Website and Install the Tracking Code

To start collecting analytics, add the website you want to measure. In the dashboard, open Administration (the cog icon), then Websites and Manage. Select Add a new measurable, give it a name and its URL, set the time zone and currency, and save.

Next to each website, choose View Tracking code to copy the JavaScript snippet Matomo generates. Paste that snippet into the <head> of every page you want to track, or install it through your tag manager or CMS plugin. Matomo also offers a Matomo Tag Manager and ready made integrations for common platforms. As soon as the tracking code runs on your site, visits, page views and events appear in the Visitors and Behaviour reports in real time.

Step 9: Use the Reporting API

Every report in Matomo is also available programmatically through the Reporting API on the same port 80. Create a per user API token (a token_auth) from Administration, then Personal, then Security, under Auth tokens. With a token you can pull any report as JSON, XML or CSV. For example, fetch the Matomo version to confirm API access, replacing <instance-public-ip> and <token>:

http://<instance-public-ip>/index.php?module=API&method=API.getMatomoVersion&format=json&token_auth=<token>

Treat API tokens like passwords and scope them to the minimum access each integration needs.

Step 10: The Data Volume

The Matomo analytics database lives on a dedicated EBS volume mounted at /var/lib/mysql. This keeps the database off the operating system disk and lets you resize or snapshot it independently. Confirm the mount with:

df -h /var/lib/mysql

To grow the database store, expand the EBS volume in the AWS console, then grow the filesystem on the instance with sudo resize2fs on the underlying device. Because the database is on its own volume, you can snapshot it for backup or detach and reattach it to a replacement instance.

Step 11: Enable HTTPS

The dashboard is served over plain HTTP on port 80 by nginx. For production use, place it behind TLS. Obtain a certificate for your domain (for example with a managed certificate on an Application Load Balancer in front of the instance, or with Certbot installed on the instance), then configure nginx to listen on 443 with your certificate and proxy to php-fpm exactly as the bundled site does for port 80. Add your domain to the Matomo trusted hosts as shown in Step 7, set force_ssl = 1 in the [General] section of config.ini.php so Matomo issues secure cookies and redirects, and restrict the security group so ports 80 and 443 are reachable only from the networks that need the dashboard.

Step 12: Backup and Maintenance

Back up Matomo by snapshotting the /var/lib/mysql EBS volume, which captures the entire analytics database, and by keeping a copy of /var/www/matomo/config/config.ini.php, which holds the database credentials, the encryption salt and the trusted hosts. You can also take a logical dump of the database with mysqldump over the loopback socket. Apply operating system security updates with sudo apt-get update && sudo apt-get upgrade and reboot when a new kernel is installed; MariaDB, php-fpm and nginx start automatically on boot. Upgrade Matomo itself from within the dashboard or with sudo -u www-data php /var/www/matomo/console core:update after backing up the database.

Support

This image is published and supported by cloudimg. Support covers deployment, website and tracking code setup, the Reporting API, user management, GDPR and privacy configuration, database tuning, TLS and scaling. Contact cloudimg through the support channel listed on the AWS Marketplace listing.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.