English ▼
Skip to page content Skip to main navigation
e.g. "templates" or "datastore"

# Using a Custom Domain

When you create a new application with Google App Engine, your app is served on the appspot.com domain. If you want your application to be served on a custom domain in addition to appspot.com, you can use a domain you already control or you can register a new one. If you prefer, you can serve your application on all subdomains in a given custom domain by using wildcard subdomain mapping.

## Serving Your App on a Custom Domain

To serve your app on a custom domain, you must tell Google Apps to handle requests on that domain. Follow these steps.

1. Go to http://appengine.google.com and click the name of the application to see its dashboard. On the left, click "Application Settings" (in the "Administration" section).

2. Click Add Domain.

3. If you have a domain and it's already managed by Google Apps, enter the domain name in the Domain Name box and click Add Domain, then skip ahead to step 4 in this list.

   Otherwise, click Sign up for Google Apps and continue with this step.

   Proceed through the Google Apps signup process, either using an existing domain name or registering a new one. When you have finished the Google Apps process, you'll reach the Google Apps dashboard. Next to the Service Settings heading, click Add More Services. (If you don't see this link, your domain name payment might not be processed yet. Refresh the page periodically until the "Your domain is not yet ready" message goes away.)

   Under Google App Engine, enter your app ID in the text box and click Add It Now.

4. Read and accept the terms of service, then click Activate This Service.

5. Click Add New URL.

   If you want to serve your app on the `www` subdomain, skip the rest of this step and continue with step 6 in this list.

   To serve your app on a single subdomain, type the subdomain name, such as `testapp` or `mytest.testapp`. (Note that your registered domain, such as `example.com`, and a preceding period are already entered on the page; don't type them.)

   To serve your app on all subdomains within a given higher-level subdomain, you can use wildcard subdomain mapping: enter an asterisk in place of the lowest-level name. For example, entering `*` will cause your app to be served on all subdomains within your registered domain. A wildcard subdomain allows you to serve different versions and backends of your application from different subdomains, as described in More About Wildcard Subdomain Mapping.

   If a page appears containing instructions about changing a CNAME record, follow those instructions. The details of these instructions depend on your DNS provider (typically, this is the same as your domain registrar).

   Click Add, and you're done.

6. (Instructions continue here if you're serving your app on the `www` subdomain.) Google Apps maps the `www` subdomain to Google Sites by default, so you must remove this mapping. Click Service Settings and choose Sites.

7. Click Web Address Mapping. Click the check box for the www mapping, then click Delete Mappings. Click again to confirm that you want to delete.

8. Click Service Settings and choose your app. It should be at the bottom of the list.

9. Click Add New URL, type `www` for the subdomain name, and click Add. You're done.

## 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 backend name, the application serves that version. If the user browses a domain that matches a backend name, the application serves that backend. For example, suppose you set up a wildcard subdomain `*.wild.example.com`. Your application has two versions, the default version and one named `beta`. Your application has a backend server named `be` with just one backend 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` backend server.
- `0.be.wild.example.com` serves the zeroth instance of the `be` backend server.
- `something.0.be.wild.example.com` also serves the zeroth instance of the `be` backend server.
- `1.be.wild.example.com` serves an error message, but if the `be` backend 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.