Associating Your Domain

Associating Your Domain

Overview:

Your Matomo is reachable at its IP address over plain HTTP as soon as it is installed. To use your own domain name with a free SSL certificate, follow the three steps below. It takes a few minutes and does not require editing any configuration files.

Applies to EGL Build 260915.1 and later. Earlier builds did not include the setup tool.

Please note: guides written for earlier builds tell you to edit the Apache configuration file with a text editor and restart the web server. That is no longer how this works, and the file those guides name is now inside a container. Use the tool below instead.

Before You Start

• Your Matomo is installed and reachable at http://<your-aws-public-ip>/
• You have a domain name and can edit its DNS records
• Ports 80 and 443 are open in the instance security group. Port 443 is required. Certificate validation uses port 80, but your site cannot serve HTTPS without 443

Step 1: Assign an Elastic IP

Do this first, before pointing any DNS at the instance.

• An ordinary EC2 public address is temporary. It changes whenever the instance is stopped and started. If that happens after you associate a domain, your domain stops resolving and your certificate stops renewing.
• In the EC2 console, open Elastic IPs and choose Allocate Elastic IP address
• Select the new address, then Actions > Associate Elastic IP address
• Choose your Matomo instance and associate it

This cannot be done from inside the instance. AWS charges a small hourly amount for a public IPv4 address whether or not it is in use, so assigning an Elastic IP replaces the charge you are already paying for a running instance rather than adding a second one.

Step 2: Point Your Domain at the Instance

• Create an A record for the hostname you want to use, pointing at your Elastic IP address. For example, an A record named stats.example.com with your Elastic IP address as its value.
• A DNS change is not visible instantly. It becomes visible over the record’s TTL, commonly five minutes. Wait for that before moving to Step 3.

Step 3: Run the Setup Tool

1. Log in via SSH

• Use SSH to access your AWS instance:

2. Run the domain setup tool

• Run the tool and follow the prompts:

3. What the tool does

• Shows your current public address and asks you to confirm you have assigned an Elastic IP
• Asks for your domain name
• Checks that your domain actually points at this instance before doing anything. If it does not, the tool stops and changes nothing
• Requests a free Let’s Encrypt certificate and tells Matomo its new address

4. When it finishes

You will see a confirmation like this:

There is nothing further to configure. The certificate renews automatically, and it survives application updates and instance reboots.

5. Your address changes, in three places at once

Please note: Matomo refuses any request arriving under a name it has not been told to trust, and answers with a warning page rather than your site. This is a deliberate protection against host header attacks, and it is why adding a domain to Matomo is not simply a matter of pointing DNS at it. The tool adds your domain to that trusted list for you.

• Sign in at your new address, for example https://stats.example.com/, with the same username and password you have been using.
• The tool also updates the address Matomo records for itself, which is what it puts into emailed reports, password reset links and the tracking code it shows you.
• Your scheduled report processing keeps running. It reaches Matomo by an internal name that the tool deliberately leaves in place, so attaching a domain does not quietly stop your reports updating.
• Update your tracking snippet. Copy the snippet again from Administration, Websites, Tracking Code so your site sends data to the new address.

Why a Domain Is Required for HTTPS

• A certificate authority will not issue a certificate for a bare IP address, and the .compute.amazonaws.com address AWS gives your instance cannot be used either.
• This is why your Matomo is served over plain HTTP until you complete the steps above, and why the tool checks your DNS before requesting anything.

If Something Goes Wrong

The tool says your domain does not point at this instance

• The A record has not been created, or has not propagated. Give it a few minutes and try again.

The tool finishes but the site does not load over HTTPS

• Check that port 443 is open in the instance security group. This is the most common cause.

Matomo shows a warning page instead of your dashboard

• This is the trusted host check described above, and it means the name in your browser is not one Matomo has been told about. It usually means you reached the site by a hostname other than the one you gave the tool, for example the www. form when you registered the bare name.
• Run the tool again with the exact hostname you want to use.

Your site stops working after stopping and starting the instance

• The public address has changed, which is what an Elastic IP prevents. Assign one, update your A record to the new address, and run the tool again.

Still stuck

• Email [email protected] with your domain name and the output of the tool, and we will help you from there.

Changing to a Different Domain Later

• Point the new hostname’s A record at the instance, then run sudo egl-setup-domain.sh.x again with the new domain. A new certificate is requested for the new name, and the new name is added to the trusted list.