Domain Mapping
In this guide, you will learn how to map a custom domain name to an environment in your Atlas application and the WordPress backend that powers it. Custom domains allow you to make production environments available at a user-friendly URL like mydomain.com, but also allow some flexibility in defining how to access other environments like staging.mydomain.com,dev.mydomain.com, or cms.mydomain.com depending on your needs.
While some users may wish to customize non-production environment URLs as well, doing so is not required; the URLs that Atlas automatically generates for environments can continue to be used. Assigning a custom domain to your WordPress backend is also optional but strongly encouraged to gain the most control over your site's resources.
Once you are in the Atlas portal, choose the app and environment that you want to map to a custom domain. When you map a custom domain, you are mapping it to a specific environment. This allows you to customize your domains based on your usage, e.g. mydomain.com, staging.mydomain.com.
After selecting your environment, locate the
+ Add domainsbutton on the environment detail panel.
Locate the text input labeled
Domain URLand add your desired domain name to that input field. As you type it will validate the URL for you. Click theConfirmbutton below the input to confirm your new domain.
To apply all of your changes, click the
Save Allbutton in the top right of this panel. You will get a success message once the settings have been saved, but there may still be processes running behind the scenes to make your app available across our network.
NOTE: TheAdd Domainbutton above this panel is used for adding multiple domains to an environment, not saving the current custom domain settings.
Copy the
CNAMEandArecords on this page for your DNS provider. NOTE: Do not use theCNAMEandArecords shown in this image. Instead, copy the ones you see in the User Portal that are specific to your app.
After updating the custom domain settings in your Atlas environment, you will need to point your domain's DNS records to WP Engine servers to finish the connection. This step will vary based on your particular DNS provider, so be sure to reference their documentation on how to add a CNAME or A record.
Once your domains are added to an environment (which requires adding them in the User Portal and clicking Save All to trigger a redeployment of your app), you can define domain-level redirect rules in the same screen. You can do it by clicking on the Edit button next to your domain name:
To specify a redirect rule, select a domain from the dropdown that will be the destination domain for the redirect.
Once confirmed, you can inspect your rules in the Redirects to column. For changes to take place, you need to click the Save All button and redeploy your app. Your redirect rules will work as expected only if both your target and destination domain are properly configured (including the DNS details).
Note: at the moment it is not possible to define redirect rules through the Atlas CLI. If changes done through CLI are expected to conflict with redirect rules set in the User Portal, this operation will be stopped and changes requested through CLI will not take place.
DNS can be inherently difficult to troubleshoot. Depending on your provider and your TTL (time to live) settings, it could take up to 24 hours for changes to your DNS records to propogate across the web. When in doubt, waiting an appropriate length of time can be a better troubleshooting step than making lots of changes very quickly.
If you click Manage Domains from the main environment screen, you should see an icon that reflects the status of your custom domain.
A green check mark indicates that everything is configured appropriately, but other statuses are possible. To get additional details, you can hover over the status icon to reveal a tooltip.
If your domain name resolves but shows either a Cloudflare error or an error regarding SSL versions, its possible that the Atlas platform is still provisioning the resources required to support your custom domain name. If either of these errors persist, please reach out to support.
As you prepare your site for production, it is strongly recommended that you assign a custom domain to the WordPress backend site by following WP Engine's Add Domain in User Portal guide.
Without a custom domain name enabled, WP Engine will apply strict settings in your site's robots.txt file to protect it during development that may not be desierable for production sites.
Assigning a custom domain provides you with the ability to customize the WordPress site's robots.txt file to allow access to some of the site's assets. For example, a meta tag like the one below, which specifies a social image for a post, may not load correctly in Twitter or other social services using the default robots.txt configuration applied to sites with the default domains your-cms.wpenginepowered.com or your-cms.wpengine.com:
<meta property="og:image" content="https://you-cms.wpenginepowered.com/wp-content/uploads/2023/01/site-image.jpg" />
Creating a custom robots.txt file allows you to define rules specific to your headless implementation. If you want to learn more about using robots.txt or ways to create a custom file on the WP Engine platform, you can reference this guide on robots.txt for more details.
Choosing good domain names for the parts of your application is important to its overall organization. While there is no "correct" choice, there are successful patterns you can emulate.
Using distinct root-level domains for your frontend and backend such as frontend-js-app.com and backend-wp-site.com is one option.
Another common pattern is to use a root-level domain for the frontend JS app, and a subdomain that points to the WordPress instance, such as:
example.com-> frontend JS appapi.example.com-> backend WP site