Use a Custom Domain Name
Overview
You can use your own custom domain name for your hosted content. By default, content that you upload is available at a domain with the following form:
<Your App ID>.mongodbstitch.com
You can configure a custom domain name for your application's hosted
content from the App Services UI or by importing an application configuration
directory that specifies the domain in its config.json
configuration
file. Select the tab below that corresponds to the method you want to
use.
Procedure
Specify the Custom Domain in Atlas App Services
You need to provide your custom domain name to App Services before it will serve content from the domain. To specify the domain:
Click Hosting in the left navigation menu.
Click the Settings tab.
Under Custom Domain, set the toggle to Enabled.
Enter your custom domain in the input box under the Enabled toggle. This value should be the root domain without any subdomains. For example, you should enter
example.com
instead ofwww.example.com
.Click Save.
Note
If an error is encountered during custom domain name validation, App Services sends the project owner an email alerting them of the issue.
Add a Validation CNAME Record
To verify that you own the domain you must add a new CNAME record in your domain's DNS configuration. The Custom Domain section will include an information box that lists the host name and target value to use in the record.
Once you have added the validation record it may take some time for the
DNS record to propagate. App Services will periodically check the domain's
DNS records for the validation CNAME
and will mark the domain as
verified if it finds the record.
Tip
Troubleshooting
In the Name field of the App Services UI, App Services provides the full address for the CNAME record,
<Subdomain>.<Your Base Domain>
. However, many hosting providers just request the<Subdomain>
part to put in their UI. If you run into issues, check your hosting provider's documentation on how to add CNAME records.App Services may not be able to find the validation record if your DNS provider proxies requests for the domain. If App Services cannot validate your domain, ensure that you have disabled any HTTP proxies for the validation CNAME record on your DNS provider.
If an error is encountered during custom domain name validation, App Services sends the project owner an email alerting them of the issue.
Add a Redirect CNAME Record
Once App Services has verified your domain, all that's left is to add a
CNAME
DNS record for your domain that points to the default App Services
domain. Use the following host name and target value:
Value | Description | |
---|---|---|
Host Name | A subdomain such as www . | |
Target | The default domain for your application. This value is listed as the App Services Domain in the Settings tab of the Hosting page. The default domain has the following form:
|
Pull the Latest Version of Your App
To configure a custom domain name with the App Services CLI, you need a local copy of your application's configuration files.
To pull a local copy of the latest version of your app, run the following:
appservices pull --remote="<Your App ID>"
Tip
You can also download a copy of your application's configuration files from the Deploy > Import/Export App screen in the App Services UI.
Specify the Custom Domain
In hosting/config.json
, set custom_domain
to your custom domain name
then save the file.
{ "enabled": true, "custom_domain": "example.com" }
Note
The value of custom_domain
should be the root domain without
any subdomains. For example, you should enter example.com
instead of www.example.com
.
Deploy the Updated Hosting Configuration
Once you've updated and saved hosting/config.json
you can push the updated
config to your remote app. App Services CLI immediately deploys the configuration on
push and App Services immediately starts trying to verify your domain name.
appservices push --remote="<Your App ID>" --include-hosting
Add a Validation CNAME Record
To verify that you own the domain you must add a new CNAME record in your domain's DNS configuration. You can find the host name and target value to use in the record Custom Domain section of the Hosting > Settings tab in the App Services UI.
Once you have added the validation record it may take some time for the
DNS record to propagate. App Services will periodically check the domain's
DNS records for the validation CNAME
and will mark the domain as
verified if it finds the record.
Tip
Troubleshooting
In the Name field of the App Services UI, App Services provides the full address for the CNAME record,
<Subdomain>.<Your Base Domain>
. However, many hosting providers just request the<Subdomain>
part to put in their UI. If you run into issues, check your hosting provider's documentation on how to add CNAME records.App Services may not be able to find the validation record if your DNS provider proxies requests for the domain. If App Services cannot validate your domain, ensure that you have disabled any HTTP proxies for the validation CNAME record on your DNS provider.
If an error is encountered during custom domain name validation, App Services sends the project owner an email alerting them of the issue.
Add a Redirect CNAME Record
Once App Services has verified your domain, all that's left to do is to add one or
more CNAME
DNS records for your domain that point to the default
App Services domain. Use the following host name and target value:
Value | Description | |
---|---|---|
Host Name | A subdomain such as www . | |
Target | The default domain for your application. This value is listed as the App Services Domain in the Settings tab of the Hosting page. The default domain has the following form:
|
Note
Add App Services's AWS CAAs to Verify Your Domain
If you have trouble verifying your domain:
clear any unnecessary CAA's from your site's records
add the following CAA records:
DomainRecord TypeFlagsTagValuewww.example.com
CAA
0
issue
"amazon.com"
www.example.com
CAA
0
issue
"amazontrust.com"
www.example.com
CAA
0
issue
"awstrust.com"