How to deploy Matomo in AWS Cloud?

Amazon Web Services (AWS) provides a reliable platform for running Matomo On-Premise with scalable compute, managed databases, and optional high-availability setups. This guide explains how to deploy Matomo On-Premise on AWS using a standard EC2-based setup that includes:

• EC2 to run Matomo, PHP, and a web server such as Apache or Nginx.
• Amazon RDS to host the Matomo database.
• Amazon EFS for shared file storage when running Matomo across multiple application servers.
• Application Load Balancer (Optional) for distributing traffic in larger or high-availability deployments.
• Amazon CloudWatch (Optional) for log collection and basic monitoring.

A single-server deployment only requires EC2 and RDS while EFS, ALB, and CloudWatch become relevant for high-availability and scaling requirements.

Ensure you have an AWS account setup with permission to create EC2 instances, RDS databases, and security groups. You do not need an existing Matomo account or prior Matomo setup as it will be installed during the set up.

Launch an AWS EC2 instance

When setting up the instance ensure you select one region and stick to that region.

1. Open your AWS console and navigate to EC2 > Instances.

2. Click Launch Instances and create a new or select an existing instance.
   

3. Configure the settings according to your requirements. This guide uses Amazon Linux (2023) for the example setup.
   

4. Review the recommended instance type server sizes mapped from Matomo’s hardware requirements to AWS EC2 instance types. AWS vCPU/RAM ratios mean AWS servers often provide more RAM, which improves performance.
5. Create a new key pair and save the downloaded file.
6. Define the security group for testing:
   • Allow inbound HTTP (80) or HTTPS (443).
   • Allow SSH (22) from your IP.
7. Click Launch Instance to finish.

Connect to the EC2 instance via SSH client

After creating your EC2 instance, connect to it using SSH and install the web server, PHP, and required PHP extensions directly on the instance.

1. In the AWS Console, go to EC2 > Instances.
2. Select the instance you created and click Connect to view the SSH connection details.
   
3. Locate the key pair file that was downloaded when creating the instance.
4. Open a terminal or PowerShell on your local machine and connect using the SSH details, for example: ssh -i my-keypair.pem ec2-user@<EC2_PUBLIC_IP>
5. If you encounter authentication or permission errors, check the following:
   • You are using the correct AWS region.
   • The key pair matches the instance.
   • You are connecting as ec2-user or the correct user if configured differently.

Create the Amazon RDS

1. In your AWS console, navigate to Aurora and RDS and click Create database.
2. Choose the database engine type according to your requirements. For example, MySQL, MariaDB, or Aurora.
   
3. Configure the credentials and note the following details will be required when installing Matomo and connecting to the database:
   • DB instance identifier.
   • Master username.
   • Master password.
4. It is optional to automatically connect the database to the EC2 instance when the database is built. Select Connect to an EC2 compute resource and choose the instance you created for Matomo.
5. Click Create database to start the process.
6. Once created, click on the database name to view the connectivity details. Copy the Endpoint URL provided, e.g. database-1.xxxxxxx.ap-xxxxxx-6.rds.amazonaws.com as you will need to provide this when installing Matomo later.
7. Ensure your RDS security group allows inbound MySQL/Aurora (3306) connections from the EC2 security group used by your Matomo instance. Open the DB instance info to view the connected security groups.

Install the web server and PHP

This step is what enables the EC2 instance as a web server capable of running Matomo.

1. Once connected to the EC2 instance, install the web server and PHP. For Amazon Linux (2023):
   sudo dnf install -y php php-cli php-fpm php-mysqlnd php-gd php-xml php-mbstring php-opcache php-soap php-curl php-zip
2. Start Apache: sudo systemctl start httpd
3. Enable Apache: sudo systemctl enable httpd
4. Check Apache is running: sudo systemctl status httpd
5. To test you can access the instance in your browser, open http://<EC2_PUBLIC_IP>/. The Public IPv4 address is shown in your EC2 Instance details.

If the site doesn’t load:

1. Open EC2 > Instances and select the instance.
2. Go to the Security tab and click the attached Security Group.
3. Check the Inbound rules include HTTP (Port: 80) and Source: MyIP (for testing). If the rule is missing, add it and save.
4. Retry loading the instance http://<EC2_PUBLIC_IP>/.

Download Matomo on the EC2 instance

Once PHP, the web server, and the database are in place, download and install Matomo on the EC2 instance. Matomo is installed directly on the server and served by Apache or Nginx.

While connected to the EC2 instance via SSH, run the following commands:

cd /var/www/html 
sudo curl -O https://builds.matomo.org/matomo.zip 
sudo unzip matomo.zip 
sudo chown -R apache:apache matomo

These commands download the latest Matomo release, extract it into the web root, and set the correct file ownership for the web server. Matomo is now installed on the EC2 instance.

Note: Whether curl is available depends on the operating system used on your EC2 instance. macOS, most Linux distributions, and some Windows versions include it by default. To confirm, open a terminal, such as PowerShell or Terminal, and run curl --version. If the command is not recognised, download and install curl from the official site at http://curl.se.

Install Matomo

1. To run the Matomo installer, open your browser and navigate to http://<EC2_PUBLIC_IP>/matomo.
2. Go through the installer steps and enter the database connection details created in AWS:
   • RDS endpoint as the database server.
   • Database name (DB identifier).
   • Master username and password.
3. Create the Matomo administrator account.
4. Complete the setup.
5. Once the installer finishes, Matomo is ready to use and connected to your RDS database.
6. Copy the tracking code from the Matomo install page and add it before the closing </head> tag on the web pages you want to track.

Important: Secure access to the EC2 instance

After testing your Matomo installation, secure your deployment before using it in production:

• Enable HTTPS by configuring an SSL certificate (for example, using AWS Certificate Manager with a load balancer or a certificate on the EC2 instance). HTTPS requires both port 443 and SSL configuration.
• Restrict access to known IP addresses by tightening EC2 security group rules to prevent unauthorised access.

CloudWatch Logs and log rotation

You can optionally use Amazon CloudWatch to monitor the health and performance of your Matomo deployment. It is typically used in larger deployments or environments that require monitoring, alerting, or operational visibility.

1. From the AWS console, open Management & Governance > CloudWatch.
2. CloudWatch supports centralised log collection, metrics and dashboards, alarms and event-based alerts.
   
3. You should still configure log rotation locally to manage log file size and disk usage.

Recommended instance type server sizes

Recommended instance type server sizes mapped from Matomo’s hardware requirements to AWS EC2 instance types. AWS vCPU/RAM ratios mean AWS servers often provide more RAM, which improves performance.

EFS (only for multi-server setups)

If you deploy more than one Matomo EC2 instance behind a load balancer, each instance must read and write the same application data. To support this, Amazon EFS is used as shared storage. The following Matomo directories must be shared across all application servers:

• /config/ (contains config.ini.php to store database credentials and core configuration).
• /misc/user/ (uploaded logos, assets).
• /js/ (Matomo JavaScript trackers and Tag Manager containers).

All of the directories listed above exist inside the Matomo installation directory, for example:

/var/www/html/matomo/config/
/var/www/html/matomo/misc/user/
/var/www/html/matomo/js/

In a multi-server setup, EFS is mounted so that these directories are shared across instances, either by:

• Mounting EFS directly at /var/www/html/matomo, or
• Mounting EFS and symlinking the required subdirectories

The exact mounting approach depends on your infrastructure design. Without EFS, each EC2 instance would have its own copy of these files, which makes Matomo behave inconsistently or fail. To backup your EFS content, refer to the AWS guide.

If you are running Matomo on a single EC2 instance. For single-server deployments, local storage on EC2 (EBS) is sufficient and doesn’t require EFS.