Associating Your Domain

Associating Your Domain

Overview:

Your Mautic instance 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 260906.2 and later. Earlier builds do not include the setup tool.

Before You Start

• Your Mautic instance 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 Mautic 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 mautic.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 Mautic 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.

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.
• HTTPS therefore begins when you associate a domain, and not before. This is a rule of the certificate system rather than a limitation of this image.

If Something Goes Wrong

“your domain currently resolves to a different address”

• You have not created or updated the A record yet. Create it, pointing at the address the tool showed you.
• Or you have just updated it and the old value is still cached. Wait a few minutes, up to the record’s TTL, and run the tool again.
• This check protects you: Let’s Encrypt permits only five failed validations per hostname per hour, and running before DNS is ready uses up that allowance.

“your domain does not resolve yet”

• 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.

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.