Sign in

1. Products
2. Google Cloud Platform
3. Google App Engine
4. Go

Go

Feedback on this document

Configuring with app.yaml

Python | Java | PHP | Go

A Go App Engine application can be configured by a file named app.yaml that specifies how URL paths correspond to request handlers and static files. It also contains information about the application code, such as the application ID and the latest version identifier.

Note: If you created your project using the Google Developers Console , your project has a title and an ID. In the instructions that follow, the project title and ID can be used wherever an application title and ID are mentioned. They are the same thing.

1. About app.yaml
2. Required elements
3. Script handlers
4. Static file handlers
   • Static directory handlers
   • Static file pattern handlers
   • Static cache expiration
5. Includes
6. Secure URLs
7. Requiring login or administrator status
8. Skipping files
9. Reserved URLs
10. Inbound services
11. Warmup requests
12. Administration console custom pages
13. Custom error responses
14. Custom PageSpeed configuration
15. Auto ID policy

About app.yaml

A Go app specifies runtime configuration, including versions and URLs, in a file named app.yaml . The following is an example of an app.yaml file for a Go application:

application: myapp
version: 1
runtime: go
api_version: go1

handlers:
- url: /stylesheets
  static_dir: stylesheets

- url: /(.*\.(gif|png|jpg))$
  static_files: static/\1
  upload: static/.*\.(gif|png|jpg)$

- url: /.*
  script: _go_app

The syntax of app.yaml is the YAML format. For more information about this syntax, see the YAML website .

The YAML format supports comments. A line that begins with a pound ( # ) character is ignored:

# This is a comment.

URL and file path patterns use POSIX extended regular expression syntax , excluding collating elements and collation classes. Back-references to grouped matches (e.g. \1 ) are supported, as are these Perl extensions: \w \W \s \S \d \D

Required elements

An app.yaml file must include one of each of the following elements:

application

The application identifier. This is the identifier you selected when you created the application in the Google Developers Console .

application: myapp

version

A version specifier for the application code. App Engine retains a copy of your application for each version used. An administrator can change which major version of the application is default using the Google Developers Console , and can test non-default versions before making them default. (The default version is loaded when no version is specified or an invalid version is specified.) The version specifier can contain lowercase letters, digits, and hyphens. It cannot begin with the prefix ah- and the names default and latest are reserved and cannot be used. Each version of an application retains its own copy of app.yaml . When an application is uploaded, the version mentioned in the app.yaml file being uploaded is the version that gets created or replaced by the upload.

version: 2-0-test

runtime

The name of the App Engine runtime environment used by this application. To specify Go, use go. Other runtimes are available; please refer to the runtime's documentation for more info. Other JVM languages can customize app.yaml based on the specified runtime.

runtime: go

handlers

A list of URL patterns and descriptions of how they should be handled. App Engine can handle URLs by executing application code, or by serving static files uploaded with the code, such as images, CSS or JavaScript. Patterns are evaluated in the order they appear in the app.yaml , from top to bottom. The first mapping whose pattern matches the URL is the one used to handle the request.

There are two kinds of handlers: script handlers, and static file handlers. A script handler runs a Go script in your application to determine the response for the given URL. A static file handler returns the contents of a file, such as an image, as the response. See Script Handlers and Handlers for Static Files below for more information on this value.

handlers:
- url: /images
  static_dir: static/images

- url: /.*
  script: _go_app

Notice that you can specify a handler in either of two ways:

• Directly under the handlers: element, as shown above.
• Indirectly in .yaml files that are included under the includes: element.

The following example shows included .yaml files, with handlers defined there instead of inside the app.yaml file that includes those other .yaml files:

includes:
- cloud_endpoints.yaml
- web_interface.yaml
- admin_interface.yaml

The included .yaml files would have the handlers directly defined under handlers: element.

api_version

The version of the API in the given runtime environment used by this application. When Google releases a new version of a runtime environment's API, your application will continue to use the one for which it was written. To upgrade your application to the new API, you change this value and upload the upgraded code.

At this time, App Engine has one version of the go runtime environment: go1

api_version: go1

Script handlers

A script handler executes a Go script to handle the request that matches the URL pattern. The mapping defines a URL pattern to match, and the script to be executed.

url

The URL pattern, as a regular expression. The expression can contain groupings that can be referred to in the file path to the script with regular expression back-references. For example, /profile/(.*?)/(.*) would match the URL /profile/edit/manager and use edit and manager as the first and second groupings.

script

Specifies the path to the script from the application root directory:

handlers:

# The root URL (/) is handled by the Go application. No other URLs match this pattern.
- url: /
  script: _go_app

# The URL /index.html is also handled by the Go application.
- url: /index\.html
  script: _go_app

# A regular expression indicating that it should be handled by the Go application.
- url: /browse/(books|videos|tools)
  script: _go_app

# All other URLs are handled by the Go application.
- url: /.*
  script: _go_app

Static file handlers

Static files are files to be served directly to the user for a given URL, such as images, CSS stylesheets, or JavaScript source files. Static file handlers describe which files in the application directory are static files, and which URLs serve them.

For efficiency, App Engine stores and serves static files separately from application files. Static files are not available in the application's file system. If you have data files that need to be read by the application code, the data files must be application files, and must not be matched by a static file pattern.

Static file handlers can be defined in two ways: as a directory structure of static files that maps to a URL path, or as a pattern that maps URLs to specific files.

Static directory handlers

A static directory handler makes it easy to serve the entire contents of a directory as static files. Each file is served using the MIME type that corresponds with its filename extension unless overridden by the directory's mime_type setting. All of the files in the given directory are uploaded as static files, and none of them can be run as scripts.

A static directory example:

handlers:
# All URLs beginning with /stylesheets are treated as paths to static files in
# the stylesheets/ directory.
- url: /stylesheets
  static_dir: stylesheets

url

A URL prefix. This value uses regular expression syntax (and so regexp special characters must be escaped), but it should not contain groupings. All URLs that begin with this prefix are handled by this handler, using the portion of the URL after the prefix as part of the file path.

static_dir

The path to the directory containing the static files, from the application root directory. Everything after the end of the matched url pattern is appended to static_dir to form the full path to the requested file.

All files in this directory are uploaded with the application as static files.

application_readable

Optional. By default, files declared in static file handlers are uploaded as static data and are only served to end users, they cannot be read by an application. If this field is set to true, the files are also uploaded as code data so your application can read them. Both uploads are charged against your code and static data storage resource quotas .

mime_type

Optional. If specified, all files served by this handler will be served using the specified MIME type. If not specified, the MIME type for a file will be derived from the file's filename extension.

For more information about the possible MIME media types, see the IANA MIME Media Types website .

http_headers

Optional. HTTP headers to use for all responses from these URLs.

handlers:
- url: /images
  static_dir: static/images
  http_headers:
    X-Foo-Header: foo
    X-Bar-Header: bar value

CORS Support

One important use of this feature is to support cross-origin resource sharing (CORS), such as accessing files hosted by another App Engine app.

For example, you could have a game app mygame.appspot.com that accesses assets hosted by myassets.appspot.com . However, if mygame attempts to make a JavaScript XMLHttpRequest to myassets , it will not succeed unless the handler for myassets returns an Access-Control-Allow-Origin: response header containing the value http://mygame.appspot.com .

Here is how you would make your static file handler return that required response header value:

handlers:
- url: /images
  static_dir: static/images
  http_headers:
    Access-Control-Allow-Origin: http://mygame.appspot.com

expiration

Optional. The length of time a static file served by this handler ought to be cached by web proxies and browsers. The value is a string of numbers and units, separated by spaces, where units can be `d` for days, `h` for hours, `m` for minutes, and `s` for seconds. For example, "4d 5h" sets cache expiration to 4 days and 5 hours after the file is first requested. See Static cache expiration . If omitted, the application's default_expiration is used.

Static file pattern handlers

A static file pattern handler associates a URL pattern with paths to static files uploaded with the application. The URL pattern regular expression can define regular expression groupings to be used in the construction of the file path. You can use this instead of static_dir to map to specific files in a directory structure without mapping the entire directory.

Static files cannot be the same as application code files. If a static file path matches a path to a script used in a dynamic handler, the script will not be available to the dynamic handler.

A static file pattern example:

handlers:
# All URLs ending in .gif .png or .jpg are treated as paths to static files in
# the static/ directory. The URL pattern is a regexp, with a grouping that is
# inserted into the path to the file.
- url: /(.*\.(gif|png|jpg))$
  static_files: static/\1
  upload: static/.*\.(gif|png|jpg)$

The following static_dir and static_files handlers are equivalent:

handlers:
- url: /images
  static_dir: static/images

- url: /images/(.*)
  static_files: static/images/\1
  upload: static/images/.*

url

The URL pattern, as a regular expression. The expression can contain groupings that can be referred to in the file path to the script with regular expression back-references. For example, /item-(.*?)/category-(.*) would match the URL /item-127/category-fruit , and use 127 and fruit as the first and second groupings.

handlers:
- url: /item-(.*?)/category-(.*)
  static_files: archives/\2/items/\1

static_files

The path to the static files matched by the URL pattern, from the application root directory. The path can refer to text matched in groupings in the URL pattern.

As in the previous example, archives/\2/items/\1 inserts the second and first groupings matched in place of \2 and \1 , respectively. With the pattern in the example above, the file path would be archives/fruit/items/127 .

upload

A regular expression that matches the file paths for all files that will be referenced by this handler. This is necessary because the handler cannot determine which files in your application directory correspond with the given url and static_files patterns. Static files are uploaded and handled separately from application files. The example above might use the following upload pattern: archives/(.*?)/items/(.*)

application_readable

Optional. By default, files declared in static file handlers are uploaded as static data and are only served to end users, they cannot be read by an application. If this field is set to true, the files are also uploaded as code data so your application can read them. Both uploads are charged against your code and static data storage resource quotas .

mime_type

Optional. If specified, all files served by this handler will be served using the specified MIME type. If not specified, the MIME type for a file will be derived from the file's filename extension. For more information about the possible MIME media types, see the IANA MIME Media Types website .

http_headers

Optional. HTTP headers to use for all responses from these URLs.

handlers:
- url: /images/(.*)
  static_files: static/images/\1
  http_headers:
    X-Foo-Header: foo
    X-Bar-Header: bar value

expiration

Optional. The length of time a static file served by this handler ought to be cached by web proxies and browsers. The value is a string of numbers and units, separated by spaces, where units can be `d` for days, `h` for hours, `m` for minutes, and `s` for seconds. For example, "4d 5h" sets cache expiration to 4 days and 5 hours after the file is first requested. See Static cache expiration . If omitted, the application's default_expiration is used.

Static cache expiration

Unless told otherwise, web proxies and browsers retain files they load from a website for a limited period of time.

You can define a global default cache period for all static file handlers for an application by including the top-level default_expiration element. You can also configure a cache duration for specific static file handlers.

(Script handlers can set cache durations by returning the appropriate HTTP headers to the browser.)

default_expiration

Optional. The length of time a static file served by a static file handler ought to be cached by web proxies and browsers, if the handler does not specify its own expiration . The value is a string of numbers and units, separated by spaces, where units can be `d` for days, `h` for hours, `m` for minutes, and `s` for seconds. For example, "4d 5h" sets cache expiration to 4 days and 5 hours after the file is first requested. If omitted, the production server sets the expiration to 10 minutes.

For example:

application: myapp
version: 1
runtime: go
api_version: go1

default_expiration: "4d 5h"

handlers:
  # ...

Includes

While the builtins directive allows you to include modules built into the Python SDK, the includes directive allows you to include any library or module throughout your application. For example, you might include a user administration library as follows:

includes:
- lib/user_admin.yaml

App Engine resolves the included path in the following order:

• Absolute or relative path to the working directory. The specified path resolves to a file.
• Relative to the application's directory (also known as the basepath ). The basepath and path resolve to a file.
• Relative to the file that included the current file. The location of the referring file and the include path resolve to the included file.

If the include directive specifies a directory, then App Engine looks in that directory for a file called include.yaml . If the include directive is a file, then that specific file is included. Using includes retrieves only the following types of directives from the destination file (if present):

• builtins
• includes
• handlers
• admin_console

Secure URLs

Google App Engine supports secure connections via HTTPS for URLs using the *.appspot.com domain. When a request accesses a URL using HTTPS, and that URL is configured to use HTTPS in the app.yaml file, both the request data and the response data are encrypted by the sender before they are transmitted, and decrypted by the recipient after they are received. Secure connections are useful for protecting customer data, such as contact information, passwords, and private messages.

To configure a URL to accept secure connections, provide a secure parameter for the handler:

handlers:
- url: /youraccount/.*
  script: _go_app
  login: required
  secure: always

secure has the following possible values:

• optional - Both HTTP and HTTPS requests with URLs that match the handler succeed without redirects. The application can examine the request to determine which protocol was used, and respond accordingly. This is the default when secure is not provided for a handler.
• never - Requests for a URL that match this handler that use HTTPS are automatically redirected to the HTTP equivalent URL.
• always - Requests for a URL that match this handler that do not use HTTPS are automatically redirected to the HTTPS URL with the same path. Query parameters are preserved for the redirect.

Any URL handler can use the secure setting, including script handlers and static file handlers.

The development web server does not support HTTPS connections. It ignores the secure parameter, so paths intended for use with HTTPS can be tested using regular HTTP connections to the development web server.

To access the versioned appspot.com URL for your application, replace the periods that would usually separate the subdomain components of the URL with the string " -dot- ". For instance: https://*desired_version*-dot-*your_app_id*.appspot.com/ .

Google Accounts sign-in and sign-out are always performed using a secure connection, unrelated to how the application's URLs are configured.

Requiring login or administrator status

Any URL handler can have a login setting to restrict visitors to only those users who have signed in, or just those users who are administrators for the application. When a URL handler with a login setting other than optional matches a URL, the handler first checks whether the user has signed in to the application using its authentication option . If not, by default, the user is redirected to the sign-in page. You can also use auth_fail_action to configure the app to simply reject requests for a handler from users who are not properly authenticated, instead of redirecting the user to the sign-in page.

login

Determines whether the URL handler is restricted to require that the user is signed in. Has three possible values:

• optional (the default). Does not require that the user is signed in.
• required . If the user has signed in, the handler proceeds normally. Otherwise, the action given in auth_fail_action is taken.
• admin . As with required , performs auth_fail_action if the user is not signed in. In addition, if the user is not an administrator for the application, they are given an error message (regardless of the auth_fail_action setting). If the user is an administrator, the handler proceeds.

auth_fail_action

Describes the action taken when login is present and the user is not logged in. Has two possible values:

• redirect (the default). The user is redirected to the Google sign-in page, or /_ah/login_required if OpenID authentication is used. The user is redirected back to the application URL after signing in or creating an account.
• unauthorized . The request is rejected with an HTTP status code of 401 and an error message.

If an application needs different behavior, the application itself can implement the handling of user logins. See the Users API for more information.

The following example requires a login for the /profile/ directory and an administrator login for the /admin/ directory:

handlers:

- url: /profile/.*
  script: _go_app
  login: required

- url: /admin/.*
  script: _go_app
  login: admin

- url: /.*
  script: _go_app

You can configure a handler to refuse access to protected URLs when the user is not signed in, instead of redirecting the user to the sign-in page, by adding auth_fail_action: unauthorized to the handler's configuration:

handlers:
- url: /secure_api/.*
  script: _go_app
  login: required
  auth_fail_action: unauthorized

Skipping files

Files in your application directory whose paths match a static_dir path or a static_files upload path are considered to be static files. All other files in the application directory are considered to be application program and data files.

The skip_files element specifies which files in the application directory are not to be uploaded to App Engine. The value is either a regular expression, or a list of regular expressions. Any filename that matches any of the regular expression is omitted from the list of files to upload when the application is uploaded.

skip_files has the following default:

skip_files:
- ^(.*/)?#.*#$
- ^(.*/)?.*~$
- ^(.*/)?.*\.py[co]$
- ^(.*/)?.*/RCS/.*$
- ^(.*/)?\..*$

The default pattern excludes Emacs backup files with names of the form #...# and ...~ , .pyc and .pyo files, files in an RCS revision control directory, and Unix hidden files with names beginning with a dot ( . ).

If a new value is specified in app.yaml , it overrides the default value. To extend the above regular express list, copy and paste the above list into your app.yaml and add your own regular expressions. For example, to skip files whose names end in .bak in addition to the default patterns, add an entry like this to skip_files :

skip_files:
- ^(.*/)?\.bak$

Reserved URLs

Several URL paths are reserved by App Engine for features or administrative purposes. Script handler and static file handler paths will never match these paths.

The following URL paths are reserved:

• /_ah/
• /form

Inbound services

Before an application can receive email , the application must be configured to enable the service. You enable the service for a Go app by including an inbound_services section in the app.yaml file. The following inbound services are available:

• channel_presence - registers your application for notifications when a client connects or disconnects from a channel .
• mail - allows your application to receive mail
• xmpp_message - allows your application to receive instant messages
• xmpp_presence - allows your application to receive a user's chat presence
• xmpp_subscribe - allows your application to receive user subscription POSTs.
• warmup - enables warmup requests

For example, you can enable mail and warmup by specifying the following in app.yaml :

inbound_services:
- warmup

Warmup requests

App Engine frequently needs to load application code into a fresh instance. This happens when you redeploy the application, when the load pattern has increased beyond the capacity of the current instances, or simply due to maintenance or repairs of the underlying infrastructure or physical hardware.

Loading new application code on a fresh instance can result in loading requests . Loading requests can result in increased request latency for your users, but you can avoid this latency using warmup requests . Warmup requests load application code into a new instance before any live requests reach that instance.

App Engine attempts to detect when your application needs a new instance, and (assuming that warmup requests are enabled for your application) initiates a warmup request to initialize the new instance. However, these detection attempts do not work in every case. As a result, you may encounter loading requests, even if warmup requests are enabled in your app. For example, if your app is serving no traffic, the first request to the app will always be a loading request, not a warmup request.

Warmup requests use instance hours like any other request to your App Engine application. In most cases, you won't notice an increase in instance hours, since your application is simply initializing in a warmup request instead of a loading request. Your instance hour usage will likely increase if you decide to do more work (such as precaching) during a warmup request. If you set a minimum number of idle instance, you may encounter warmup requests when those instances first start, but they will remain available after that time.

inbound_services:
- warmup

This causes the App Engine infrastructure to issue GET requests to /_ah/warmup . You can implement handlers in this directory to perform application-specific tasks, such as pre-caching application data.

Administration console custom pages

If you have administrator-only pages in your application that are used to administer the app, you can have those pages appear in the Administration Console. The Administration Console includes the name of the page in its sidebar, and displays the page in an HTML iframe . To add a page to the Administration Console, add an admin_console section in your app's app.yaml file, like so:

admin_console:
  pages:
  - name: Blog Comment Admin
    url: /blog/admin/comments
  - name: Create a Blog Post
    url: /blog/admin/newentry

For each page , url is the URL path to the page, and name is what will appear in the Administration Console navigation. Custom page names can only contain ASCII characters. Custom page urls may be re-routed by rules in the dispatch file , if one exists.

Custom error responses

When certain errors occur, App Engine serves a generic error page. You can configure your app to serve a custom static file instead of these generic error pages, so long as the custom error data is less than 10 kilobytes. You can set up different static files to be served for each supported error code by specifying the files in your app's app.yaml file. To serve custom error pages, add a error_handlers section to your app.yaml , as in this example:

error_handlers:
  - file: default_error.html

  - error_code: over_quota
    file: over_quota.html

Each file entry indicates a static file that should be served in place of the generic error response. The error_code indicates which error code should cause the associated file to be served. Supported error codes are as follows:

• over_quota , which indicates the app has exceeded a resource quota ;
• dos_api_denial , which is served to any client blocked by your app's DoS Protection configuration ;
• timeout , served if a deadline is reached before there is a response from your app.

The error_code is optional; if it's not specified, the given file is the default error response for your app.

You can optionally specify a mime_type to use when serving the custom error. See http://www.iana.org/assignments/media-types/ for a complete list of MIME types.

Custom PageSpeed configuration

When enabled, PageSpeed Service will be applied globally to your application. All versions of your app will be automatically optimized with the same configuration, that of the most-recently updated version. If you want to try a new configuration, perhaps to test some "risky" optimizations, you might expect that you could do so in a test Application Version while your users continue to use the default Application Version. But since updating the test version's configuration applies to all versions, the "risky" settings are applied to the version that your users use, too. Instead, to try out these settings, you could

• Turn off PageSpeed for your application, update PageSpeed configuration, and view your site using the PageSpeed chrome extension; or
• Copy the relevant parts of your application to a separate test application that has its own application ID and versions.

PageSpeed is a family of tools for optimizing the performance of web pages. You can use the Application Console to enable PageSpeed with a solid set of safe default optimizations. You can also edit your application configuration to fine-tune PageSpeed. You can configure PageSpeed to ignore some URLs; you can turn on some "risky" optimizations that don't work for all sites but might work for yours. For a custom PageSpeed configuration, you can add a pagespeed section to your application configuration. An example that shows the possible parts (but not all choices) of pagespeed :

pagespeed:
  domains_to_rewrite:
  - www.foo.com
  - https://*.secure.foo.com
  url_blacklist:
  - http://myapp.com/blob/*
  - http://myapp.com/comments/*
  enabled_rewriters:
  - MinifyCss
  disabled_rewriters:
  - ImageStripColorProfile

This section may have any or all of the following parts:

domains_to_rewrite

Which domains' content PageSpeed should rewrite. Normally, PageSpeed only rewrites data served by your application. But you can tell PageSpeed to rewrite content from other domains when your application shows that data. For example, your application might use a free image hosting service on some other domain. Since the image hosting site isn't part of your application, PageSpeed doesn't optimize those images by default. You might want it to optimize these images: they can be compressed and cached by Google, and thus displayed faster. You might not want it to optimize these images: Since pagespeed optimizes the images, you will be charged whenever those images are served.

url_blacklist

This is a list of URLS; the * character is a wildcard. PageSpeed won't try to optimize URLs matching these URLs. This can be especially useful if you turn on some "risky" optimizations that break content for some URLs but make the rest of your site much much faster. By default, there is no blacklist.

enabled_rewriters , disabled_rewriters

By default, some "safe" optimization rewriters are turned on. Other "risky" optimizations are not turned on. You can choose more optimizations to use by listing them in enabled_rewriters ; you can turn off default rewriters by listing them in disabled_rewriters . The following rewriters are available:

HTML Rewriters

• ProxyCss - default
• ProxyImages - default
• ProxyJs - default
• ConvertMetaTags - default
• InlineCss - default
• InlineJs
• InlineImages
• InlinePreviewImages - default
• CollapseWhitespace
• CombineHeads
• ElideAttributes
• RemoveComments
• RemoveQuotes
• LeftTrimUrls

CSS Rewriters

• CombineCss - default
• MoveCssToHead - default
• MinifyCss

Image Rewriters

• WebpOptimization - default
• ImageConvertToJpeg - default
• ImageRecompressJpeg - default
• ImageProgressiveJpeg - default
• ImageRecompressPng - default
• ImageStripMetadata - default
• ImageStripColorProfile - default
• ImageResize - default
• LazyloadImages - default
• ImageAddDimensions

JavaScript Rewriters

• CombineJs - default
• JsOptimize - default
• DeferJs

Auto ID policy

If you are setting entity identifiers automatically , you can change the method employed by setting the auto ID policy. You can choose default (default is also applied if you specify nothing) or legacy. Please note however that the legacy option will be deprecated in a future release and will eventually be removed. For more information, see our blog post where we announced the change.

auto_id_policy: default