Hide
Google App Engine

Using a Custom Domain

When you create an application with Google App Engine, the app is automatically served on the appspot.com domain at your-app-ID.appspot.com. However, it's often desirable to serve your app at a custom domain that you own (example.com), at specific subdomains of that domain (app.example.com), 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:

  1. Prove to Google that you control the domain.
  2. Configure Google servers to recognize the domain.
  3. 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:

  1. 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:

    Settings page with no input

  2. 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.

  3. 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.

  4. 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.

    Domain dialog on Settings page

    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:

    List of domains and subdomains associated with this application

  5. 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 CNAME record you'll need to create at your domain registrar, pointing to the ghs.googlehosted.com subdomain. 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 A, AAAA, or 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 *.wild.example.com. 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.com serves your application.
  • beta.wild.example.com serves the beta version of your application.
  • alpha.beta.wild.example.com also serves the beta version of your application.
  • be.wild.example.com serves the be module.
  • 0.be.wild.example.com serves the zeroth instance of the be module.
  • something.0.be.wild.example.com also serves the zeroth instance of the be module.
  • 1.be.wild.example.com serves an error message, but if the be module 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:

Entering * maps all subdomains of example.com to your app.

Entering *.private maps all subdomains of private.example.com to your app.

Entering *.nichol.sharks.nhl maps all subdomains of nichol.sharks.nhl.example.com to your app.

Entering *.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 sites and mail, those mappings have higher priority and are matched first, before any wildcard mapping takes place. In addition, if you have other App Engine apps mapped to other subdomains, those mappings also have higher priority than any wildcard mapping.

Note that some DNS providers might not work with wildcard subdomain mapping. In particular, a DNS provider must permit wildcards in CNAME host entries.