Skip to main content

Custom Domain Names

Function URL​

If you are following our latest cookiecutter pattern, then you are using Lambda's free Function URLs (FURL) which allows JavaScript & Assets to work out of the box. Using a custom domain name with a FURL is as easy as adding CloudFront. To see your FURL in the AWS Console, open the Lambda section -> Click Your Function Name -> Open Versions Tab -> Open Configuration Tab -> Click alias: live. Your Function URL will appear in the upper right. Ex: uniquestring.lambda-url.us-east-1.on.aws. Custom Domain Name Steps:

API Gateway​

For API Gateway Lamby users, their Custom Domain Name featue is the only way to get JavaScript & Assets working correctly by removing the stage path. You can optionally add a CloudFront distribution above this for edge caching. Custom Domain Name Steps:

Individual Steps​

Secure Certificate with ACM​

We are going to use AWS Certificate Manager to secure your HTTPS traffic under your custom domain. Again, this assumes your domain is setup in Route53 since you will need to validate the certificate and AWS makes that super easy with DNS.

  • AWS Console -> Certificate Manager
  • Click "Request a certificate" button.
  • Select "Request a public certificate", and "Request a certificate" button.
  • Domain name. Ex: *.example.com
  • Click "Next"
  • Select "DNS validation", and "Review".
  • Click "Confirm and request" button.
  • Click the tiny disclosure triangle beside your domain name.
  • Click the "Create record in Route 53" button then "Create" again in modal.
  • Click "Continue"

Verification will take about 3 minutes. From the Certificate Manager dashboard, you can wait and/or hit the 🔄 button and the Status will change from "Pending validation" to "Issued".

Simple CloudFront Distribution​

Basic reference steps for creating a CloudFront distribution. If you are editing an existing CloudFront distribution, some of these settings might be in your default behavior vs the distribution.

  • Origin:
    • Origin Domain: Function URL or API Gateway Custom Domain Name Endpoint Config
    • Protocol: HTTPS only
    • Minimum Origin SSL Protocol: TLSv1.2
    • Origin Path: /production (⚠️ Ignore for FURLs. API Gateway stage name.)
    • Add Custom Header: X-Forwarded-Host myapp.example.com
  • Default Cache Behavior:
    • Compress Objects Automatically: Yes
    • Viewer Protocol Policy: Redirect HTTP to HTTPS
    • Allowed HTTP Methods: GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE
      • Cached HTTP Methods: ✔️ OPTIONS
    • Cache key and origin requests:
    • 🔘 Legacy cache settings:
      • Headers: Include the following headers
        • Accept
      • Query Strings: All
      • Cookies: All
      • 🔘 Use origin cache headers
  • Settings:
    • Price Class: Use only North America and Europe
    • Alternate domain name (CNAME): myapp.example.com
    • Custom SSL Certificate (select *.example.com from ACM steps)

This process takes a while to fully deploy. Once done you will have a CloudFront domain name looking something like dxxxxxxxxxxxxx.cloudfront.net. You can now Create a Route53 Record alias for myapp.example.com to this CloudFront distribution domain name.

Feel free to create an additional behavior for the /assets path using the CachingOptimized cache policy and None for the Origin request policy. This will ensure the asset pipeline files are edge-cached and compressed.

Create a Route53 Record​

From here all we need is a DNS entry in Route53 that points to our origin. Typically this would be to your CloudFront distribution. Like the one you may have created for your Function URLs or your [API Gateway](#api-gateway] custom domain name.

  • AWS Console -> Route 53 -> Hosted zones
  • Click on your domain
  • Click "Create record"
  • Click "Switch to wizard" if not selected already.
  • Select "Simple routing"
  • Click "Next"
  • Click "Define simple record"
  • Record name. Ex: myapp
  • Record type: A - Routes traffic to an IPv4 address and some AWS resources
  • Value/Route traffic to: (either or)
    • Alias to CloudFront distribution
      • Endpoint: dxxxxxxxxxxxxx.cloudfront.net
    • Alias to API Gateway API
      • Choose Region: Ex: us-east-1
      • Choose endpoint: Should autofill, Ex: d-xxxxxxxxxx.execute-api.us-east-1.amazonaws.com
  • Evaluate target health: No
  • Click "Define simple record"
  • Click "Create records"

API Gateway Custom Domain Names​

Any Web Proxy Integrations with API Gateway will need to leverage its Custom Domain Name feature. The only exception would be if you are using an Application Load Balancer without REST API. When completed, your final endpoint would look like this d-byp3km86t3.execute-api.us-east-1.amazonaws.com and would then become an CloudFront origin.

  • AWS Console -> API Gateway
  • Click "Custom domain names" in the left panel.
  • Click "Create" button
  • Enter domain name. Ex: myapp.example.com
  • Use default TLS 1.2 (recommended).
  • Endpoint type Regional.
  • ACM certificate. Select wildcard matching domain from above.
  • Click "Create domain name"

After this has been created, the mappings tab should be selected. From here we need to create an API Mapping to point to your specific API Gateway and stage/path. Assuming it is selected:

  • Click the "API mappings" tab.
  • You should see "No API mappings have been configured..." message
  • Click "Configure API mappings" button.
  • Click "Add new mapping" button.
  • Select your API: Ex: myapp (HTTP - 511n0spvi9).
  • Select your Stage: Ex: production.
    • If you see Stage and production ignore Stage. Known REST bug.
  • Leave Path empty.
  • Click the "Save" button.