When you create an application with Google App Engine,
the app is automatically served on the
appspot.com domain at
However, it's often desirable to serve your app at a custom domain that you own (
at specific subdomains of that domain (
or at any or all (
*.example.com) subdomains of that domain.
It's easy to do this with App Engine. First, of course, you must acquire a domain through a domain registrar. Once you have a domain, customizing your app to use your domain or subdomain involves three steps:
- Prove to Google that you control the domain.
- Configure Google servers to recognize the domain.
- Update the DNS records at your domain registrar to point to Google servers.
The entire process can typically be completed in a few minutes at your computer.
Note that the instructions on this page are for App Engine apps that use an ordinary HTTP connection and are not served through Google Apps. Here are some related procedures that require different instructions:
- To serve your App Engine app through Google Apps, read about App Engine in the Google Apps help center.
- To assign an additional domain to your Google Apps services, read about custom domains in the Google Apps help center.
- To add Secure Sockets Layer (SSL) encryption (i.e., an HTTPS address) to your App Engine app, you must use the SSL service provided with Google Apps. You'll find information and instructions at SSL for a Custom Domain.
Serving your app on a custom domain
If you do not already have a domain to use, purchase one online from a domain registrar. (Search "domain registrar" for some examples.) Once you have a domain, follow these steps to use it with your App Engine application:
Go to the Google Developers Console at https://console.developers.google.com and select your project to see its dashboard. At the left of the dashboard, select Compute > App Engine > Settings. At the top of the Settings page you may see several tabs, such as Application settings and Custom domains. Select the Custom domains tab. This displays a page with three numbered sections, similar to this:
In the first numbered section, enter your domain name and click the Verify button. This brings up a page at Webmaster Central where you can demonstrate that you control the domain. Typically it looks something like this:
If Webmaster Central doesn't display the name of your domain registrar, you may need to re-enter the domain name or manually select your registrar in the spinner control.
The Webmaster Central page displays a recommended verification method and, in some cases, an alternative. In most cases you can simply click the Verify button, log in to your registrar site, and click Accept. Otherwise, follow the instructions provided. If you want to add more sites, use the Add site button. Once you've verified control of the domain(s) you want to use, you can close the Webmaster Central window and return to Settings.
In the second numbered section on the Settings page, you can add a domain name or subdomain, or multiples of either or both. To add a domain name, click the top radio button and select the desired domain name in the spinner control next to it.
When you do, the instructions in section 3 are adjusted to match your selection. They list the DNS records you'll need to create at your domain registrar, pointing to Google servers. Use a separate browser window to log in to your registrar's site and create the resource records as indicated, or copy the instructions to complete later. On the Settings page, be sure to click the Add button. Since the domain is now associated with the application, it appears on the Custom domain names list at the bottom of the page, as shown here:
To add a subdomain, click the second radio button, enter the subdomain in the text box, and select the desired domain name in the spinner control next to it. The instructions in the third section change to reflect the information you provide, showing the
CNAMErecord you'll need to create at your domain registrar, pointing to the
ghs.googlehosted.comsubdomain. Use a separate browser window to log in to your registrar's site and create the resource records as indicated, or copy the instructions to complete later. On the Settings page, click the Add button and be sure that the subdomain appears on the list beneath Custom domain names at the bottom of the page. If desired, you can use an asterisk to indicate a wildcard subdomain as explained in detail farther below.
Each domain or subdomain that you add is added to the list. It's okay for multiple domains and subdomains to point to the same application. You can design your app to treat them all the same or handle each one in a different way. (This is not true if you're serving the application using SSL through Google Apps, as explained at SSL for a Custom Domain.)
If you're not familiar with some of this terminology, it may be helpful to read up on the Domain Name System (DNS).
Once you've added the domain(s) or subdomain(s) to the list at the bottom of the Settings page,
and have created the necessary
CNAME records at your registrar, your work is done.
The update takes time to propagate out across the Internet, and reaches different users at different times.
This can take up to two days, but for most users it is much quicker than that.
If you wish to confirm that the registrar implemented the changes, you can use DNS tools such as dig or nslookup.
More about wildcard subdomain mapping
If you set up a wildcard subdomain mapping for your custom domain, then your application serves requests for any subdomain that matches.
If the user browses a domain that matches an application version name or module name, the application serves that version.
If the user browses a domain that matches a module name, the application serves that module.
For example, suppose you set up a wildcard subdomain
Your application has two versions, the default version and one named
beta, and a module named
be with just one module instance running.
whatever.wild.example.comserves your application.
betaversion of your application.
alpha.beta.wild.example.comalso serves the
betaversion of your application.
0.be.wild.example.comserves the zeroth instance of the
something.0.be.wild.example.comalso serves the zeroth instance of the
1.be.wild.example.comserves an error message, but if the
bemodule was provisioned with more than one instance, then this would serve the first (after zeroth) instance.
You can use wildcards to map subdomains at any level, starting at third-level subdomains. For example, if your domain is
example.com and you enter text in the web address field:
* maps all subdomains of
example.com to your app.
*.private maps all subdomains of
private.example.com to your app.
*.nichol.sharks.nhl maps all subdomains of
nichol.sharks.nhl.example.com to your app.
*.excogitate.system maps all subdomains of
excogitate.system.example.com to your app.
If you use Google Apps with other subdomains on your domain, such as
Note that some DNS providers might not work with wildcard subdomain mapping. In particular, a DNS provider must permit wildcards in CNAME host entries.