Associating Your Domain

Associating Your Domain

Overview:

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

Do this before your agents and customers start using the helpdesk. Tickets carry names, email addresses and whole conversations, and they should not be served over plain HTTP.

Before You Start

• Your Zammad 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 Zammad 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 help.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.

Choose the hostname your customers will see. It becomes the address of your helpdesk and your customer portal, and the address in the links of every notification email Zammad sends, so pick something they will recognise such as help.example.com or support.example.com.

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 SSL certificate and tells Zammad its new address

It usually finishes in under a minute.

4. When it finishes

You will see a confirmation like this:

If the page does not open straight away, wait a few seconds and reload. There is nothing further to configure. The certificate renews automatically, and it survives application updates and instance reboots.

5. Your address changes

• You, your agents and your customers now reach the helpdesk at https://help.example.com/.
• The tool also updates the address Zammad records for itself, and switches it to HTTPS. Zammad uses that address in the links inside the notification emails it sends, so your agents and customers receive links that open your helpdesk at its new address.
• Your email address and password are unchanged.

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 helpdesk 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 site loads at the new domain, but emails still link to the old address

• The tool updates the stored address, so this should not happen. If it does, email [email protected] and we will correct it.

You are asked to sign in again

• That is expected. The address changed, so your existing session does not carry over. Sign in with the same email address and password as before.

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 stored address is updated to match.