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.) Then, click the button below to associate your application with that domain.

Select Your Project and Associate it with a Domain

On the page that follows you'll need to verify that you are the domain owner. Then, select the domain you want to use to serve your App Engine app. Finally, add the provided A, AAAA, or CNAME records that are listed in the Developers Console at your registrar.

Updates to domain records take time to propagate out across the Internet, and reach different users at different times. The process 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.

Using Strict-Transport-Security headers in a custom domain

You cannot use Strict-Transport-Security headers unless your domain is whitelisted. To place your domain in the whitelist, contact agl@chromium.org.

Subdomains

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.