Configure a Custom Domain

EMQX Cloud allows you to configure a custom domain for your deployment so MQTT clients can connect through a domain you own. This is useful when you want to provide a stable, branded endpoint and let EMQX Cloud manage the TLS/SSL certificate for that domain.

Note

This feature is available only for EMQX v5 Dedicated Flex deployments. It is not supported for Serverless, other Dedicated plans, or v4 deployments.

Before You Start

Make sure the following requirements are met:

• Your deployment is EMQX v5 Dedicated Flex.
• You own a domain and can manage its DNS records.
• The domain must be a subdomain, such as mqtt.example.com.

Note

Wildcard domains such as *.example.com are not supported.

TIP

If you have strict compliance requirements around certificate issuance or renewal, consider uploading your own certificate instead of using a managed certificate.

Configure the Custom Domain

1. Log in to the EMQX Cloud console and navigate to the target deployment's overview page.

2. In the MQTT Connection Information section, click Custom Domain.

3. In the Domain step, enter the custom domain that MQTT clients will use to connect.

   Example:

   mqtt.example.com

   

4. Click Next to go to the DNS step. Add the CNAME record shown in the console at your DNS provider so the custom domain points to the deployment's default endpoint.

   Example (replace the target hostname with the one shown in your console):

   mqtt.example.com    CNAME    h72937f5.ala.dedicated.aws.example.com

   

5. After the DNS record is added, click Next to go to the TLS/SSL step, select Managed by EMQX Cloud, and let EMQX Cloud issue and renew a Let's Encrypt certificate for the custom domain.

   By default, the managed certificate is set to auto-renew. If needed, you can later turn off auto-renewal from TLS/SSL Config by clicking Disable Auto-Renewal.

   ::: caution After auto-renewal is disabled, it cannot be re-enabled. You must replace the certificate manually before it expires. :::

   

6. Add the ACME validation CNAME record shown in the console at your DNS provider.

   Example:

   _acme-challenge.mqtt.example.com    CNAME    _acme-challenge.h72937f5.ala.dedicated.aws.example.com

   ::: caution Keep the _acme-challenge CNAME record in place permanently. Removing it may cause certificate renewal to fail.

   If your domain uses CAA records, make sure letsencrypt.org is listed as an authorized issuer. :::

7. After the DNS and TLS/SSL configuration is ready, click Verify & Apply.

Verify the Configuration

After the configuration is applied, verify it with the following checks:

1. Return to the deployment overview page and confirm the custom domain is shown in the connection information.

2. Verify the DNS record from your local environment. On Linux and macOS, use dig:

   dig mqtt.example.com CNAME

   On Windows, use nslookup:

   nslookup mqtt.example.com

3. Verify that the issued TLS/SSL certificate matches the custom domain.

   openssl s_client -connect mqtt.example.com:8883 -servername mqtt.example.com

4. Test the connection with MQTTX or another MQTT client using the custom domain and the appropriate port for your protocol:

   • MQTT over TCP: 1883
   • MQTT over TLS/SSL: 8883
   • WebSocket: 8083
   • WebSocket over TLS/SSL: 8084

Troubleshooting

• The deployment is not EMQX v5 Dedicated Flex.

  This feature is only available for v5 Dedicated Flex deployments. Verify your deployment type in the console.

• The configured domain is not a subdomain you control.

  You must own the domain and be able to add DNS records for it. Wildcard domains are not supported.

• The DNS record is the wrong type.

  Use the exact CNAME record shown in the console. A records or other record types will not work.

• DNS propagation is still in progress.

  Wait 5–10 minutes after adding a record and try again. Use dig or an online DNS checker to confirm propagation.

• The ACME CNAME record is missing or removed after setup.

  The _acme-challenge CNAME record must remain in place permanently for certificate auto-renewal to work. Re-add it if it was removed.

• CAA records block certificate issuance.

  If your domain uses CAA records, add letsencrypt.org as an authorized issuer.