Skip to content

configuring-custom-domain.md

Latest commit

 

History

History
210 lines (141 loc) · 8.73 KB

configuring-custom-domain.md

File metadata and controls

210 lines (141 loc) · 8.73 KB

Configuring a custom domain

In this tutorial, you will configure custom domains for your web and API components. When you are done, you will be able to access the website and the HTTP APIs on your branded domain, e.g. https://contoso.com and https://api.contoso.com, in addition to the domain names provided by AWS.

LetsGo Web - Custom Domain

This tutorial assumes you have already set up authentication with Auth0 as there will be modifications necessary in your Auth0 configuration.

Get your domain

You need to own a domain name to continue with this tutorial. You can buy a domain from one of the many domain registrars like Namecheap or GoDaddy.

To continue with this tutorial, you must be able to manage DNS entries for your custom domain.

Decide what domain names to use

The web and API components of your app will be running on distinct domain names. One common pattern is to host your website on the root domain, e.g. contoso.com, and the API component on a subdomain, e.g. api.contoso.com.

Before continuing, decide what domain names will be used for the web and API components. For illustration purposes, this tutorial will assume you are using contoso.com for your web component, and api.contoso.com for the API.

Configure the custom domain for the web and API components

Start by setting up a custom domain name for the web component by running:

yarn ops domain add -a web contoso.com

Then set up a custom domain for the API component by running:

yarn ops domain add -a api api.contoso.com

The output of these commands lists several required DNS records and will look similar to this:

...
  Required DNS records:

  Name           contoso.com.
  Type           CNAME
  Value          uuinv8zkks.us-west-2.awsapprunner.com

  Name           _cf80256c9338a3db39e16ad6eb57cdb5.contoso.com.
  Type           CNAME
  Value          _c44b8cad670f892da6fad43430e80251.smwfzlpyzn.acm-validations.aws.
  Status         PENDING_VALIDATION

  Name           _7bbeb27328981b41d0ebcb6930eaa6bf.2a57j77wh7zuoxja78n16sab4p8g6xi.contoso.com.
  Type           CNAME
  Value          _90921a66e19654e4bcf60a3ed3a8f5bd.smwfzlpyzn.acm-validations.aws.
  Status         PENDING_VALIDATION
...

You must now manually create these entries in your domain registrar to complete the set up of custom domains. This process is specific to the domain registrar you are using. For example, here is the process for Namecheap, and here for GoDaddy. Other domain registrars will have similar instructions.

NOTE Some domain name registrars have restrictions on the length of keys or values of the DNS records which may prevent you from setting up the required DNS records. As a workaround, you can set up a Cloudflare account and move the management of DNS records for your custom domain there by using Cloudflare's nameservers with your custom domain in your domain registrar.

Monitor the status of your custom domain configuration

After you have added the required DNS records in your domain registrar, it may take up to 48 hours for the DNS system to fully propagate these changes (although it usually takes only minutes). During this time, you can monitor the status of your custom domain configuration by running this command for the web component:

yarn ops domain status -a web

and this command for the API component:

yarn ops domain status -a api

The output of the commands will look similar to this:

  Domain         contoso.com
  Status         pending_certificate_dns_validation

  Required DNS records:

  Name           contoso.com.
  Type           CNAME
  Value          uuinv8zkks.us-west-2.awsapprunner.com

  Name           _cf80256c9338a3db39e16ad6eb57cdb5.contoso.com.
  Type           CNAME
  Value          _c44b8cad670f892da6fad43430e80251.smwfzlpyzn.acm-validations.aws.
  Status         PENDING_VALIDATION

  Name           _7bbeb27328981b41d0ebcb6930eaa6bf.2a57j77wh7zuoxja78n16sab4p8g6xi.contoso.com.
  Type           CNAME
  Value          _90921a66e19654e4bcf60a3ed3a8f5bd.smwfzlpyzn.acm-validations.aws.
  Status         PENDING_VALIDATION

As long as the Status on the second line is different than active, your custom domain is not yet set up correctly. In the example output above the status is pending_certificate_dns_validation, which means the system was not yet able to confirm the DNS records were set up as required. This is usually because of the lag in DNS record propagation and caching. Get a coffee and keep checking.

When you run the yarn ops domain status ... command and the output shows active in the top Status line, your custom domain name has been configured correctly, for example:

  Domain         contoso.com
  Status         active

  Required DNS records:

  Name           contoso.com.
  Type           CNAME
  Value          uuinv8zkks.us-west-2.awsapprunner.com

  Name           _cf80256c9338a3db39e16ad6eb57cdb5.contoso.com.
  Type           CNAME
  Value          _c44b8cad670f892da6fad43430e80251.smwfzlpyzn.acm-validations.aws.
  Status         SUCCESS

  Name           _7bbeb27328981b41d0ebcb6930eaa6bf.2a57j77wh7zuoxja78n16sab4p8g6xi.contoso.com.
  Type           CNAME
  Value          _90921a66e19654e4bcf60a3ed3a8f5bd.smwfzlpyzn.acm-validations.aws.
  Status         SUCCESS

Only after the Status is active you can proceed to the next step.

Update the Auth0 configuration

You must add your custom domain to the Auth0 configuration to inform Auth0 that your service is now available on a new set of URLs.

In the Auth0 Management Dashboard, navigate to Applications / Applications, locate the application you have created when setting up authentication with Auth0, go to the Settings tab, find the Application URIs section, and update the configuration as follows:

  • In Allowed Callback URLs, add the URL based on your custom domain name of the web component, e.g. https://contoso.com/api/auth/callback (replace contoso.com with your domain name),
  • In Allowed logout URLs and in the Allowed Web Origins, add a URL based on your custom domain name of the web component, e.g. https://contoso.com/ (replace contoso.com with your custom domain name).
image

Scroll down to the bottom of the page and click Save Changes.

Re-deploy the app to AWS

Run the following command to re-deploy the app to AWS to complete the custom domain setup:

yarn ops deploy -a all

After deployment, you can confirm the status of the custom domain setup for the web and API components by running:

$ yarn ops status
...
Web
  Service
    Status         RUNNING
    Health         HTTP 200 (181ms)
    Url            https://uxb9hhcrtj.us-west-2.awsapprunner.com
    CustomDomain   contoso.com (active)
...
Api
  Service
    Status         RUNNING
    Health         HTTP 200 (157ms)
    Url            https://6ucstfkcn6.us-west-2.awsapprunner.com
    CustomDomain   api.contoso.com (active)
...

Notice the CustomDomain properties showing the custom domain name and its status as active for the web and API components.

Access the website at the custom domain

Point the browser at your custom domain, e.g. https://contoso.com. You should see your website.

Access the API at the custom domain

Invoke the health endpoint of your API using the custom domain, e.g.

curl https://api.contoso.com/v1/health

You should see an HTTP 200 response with a JSON response that includes the details, e.g.

{
  "ok": true,
  "imageTag": "9225060f1903ddef",
  "updatedAt": "2023-11-04T22:08:24.392Z"
}

Congratulations! You have set up a custom domain for your web and API components! Your customers can access your website and call the HTTP APIs at the custom domain now. AWS will be taking care of providing and updating the SSL certificate for the secure endpoints.