Associating Your Domain

Associating Your Domain

Overview:

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

Before You Start

• Your SuiteCRM 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 SuiteCRM 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 crm.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 SuiteCRM 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 login address changes

• Log in at your new address, for example https://crm.example.com/, using the CRMadmin username and the password shown when the CRM was installed.
• SuiteCRM records its own address, and the tool updates it, so use the new domain rather than the old IP address from now on.

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

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.

The CRM loads over HTTPS but pages look unstyled or you are logged out repeatedly

• You are almost certainly still using the old address in a browser tab or a bookmark. SuiteCRM records its own address, and the tool updates it, so the CRM must be reached at the new domain.
• Clear your browser cookies for the site and open the new address.

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.