JRuby Application Configuration

A JRuby App Engine application must have a configuration 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.

About app.yaml

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

application: myapp
version: 1
runtime: jruby
 
handlers:
- url: /admin/*
  login: admin

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

Tip: 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 file globs)

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 Administration 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 Administration Console, and can test non-default versions before making them default. The version specifier can contain letters, digits, and hyphens.

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. Use jruby to include the JRuby-Rack servlet, or java if you want to specify all the servlets yourself.

runtime: jruby

URL Handlers

app.yaml defines mappings between URL paths and the servlets that handle requests with those paths. If you use runtime: jruby, the JRuby-Rack servlet will automatically be added for you so you just need to edit config.ru for dispatching to Ruby code.

All handlers require a URL pattern. The URL pattern can use an asterisk (*) at the beginning or end of the pattern to indicate zero or more of any character. (The Java Runtime does not support wildcards in the middle of a string, and does not allow multiple wildcards in one pattern.) The pattern matches the full path of the URL, starting with and including the forward slash (/) following the domain name.

Handlers can also specify the class of a Servlet, ServletFilter, or the path to a JSP file. ou can declare multiple servlets using the same class with different initialization parameters if you specify a name.

handlers:
  - url: /red/*
     servlet: mysite.server.TeamServlet
     init_params:
       teamColor: red
       bgColor: "#CC0000"
     name: redteam
  - url: /blue/*
     servlet: mysite.server.TeamServlet
     init_params:
       teamColor: blue
       bgColor: "#0000CC"
     name: blueteam
  - url: /register/*
     jsp: /register/start.jsp
  - url: *.special
     filter: mysite.server.LogFilterImpl
     init_params:
       logType: special

Static Files and Resource Files

Many web applications have files that are served directly to the user's browser, such as images, CSS stylesheets, or browser JavaScript code. These are known as static files because they do not change, and can benefit from web servers dedicated just to static content. App Engine serves static files from dedicated servers and caches.

Files that are accessible by the application code using the filesystem are called resource files. These files are stored on the application servers with the app.

By default, all files in the WAR are treated as both static files and resource files, except for JSP files, which are compiled into servlet classes and mapped to URL paths, and files in the WEB-INF/ directory, which are never served as static files and always available to the app as resource files.

You can adjust which files are considered static files and which are considered resource files using elements in the app.yaml file. The static_files element specifies patterns that match file paths to include and exclude from the list of static files, amending the default behavior. Similarly, the resource_files element specifies which files are considered resource files.

Path patterns are specified using zero or more include and exclude elements. In a pattern, * represents zero or more of any character in a file or directory name, and ** represents zero or more directories in a path.

An include element overrides the default behavior of including all files. An exclude element applies after all include patterns (as well as the default if no explicit include is provided).

For example, to specify that all files whose names end in .png are static files (but never those in WEB-INF/) except those in the data/ directory and all subdirectories:

 
    static_files:
        - include: /**.png
        - exclude: /data/**.png

Similarly, to specify that all files whose names end in .xml are resource files (including those outside of WEB-INF/) except those in the feeds/ directory and all subdirectories:

 
    resource_files:
        - include: /**.xml
        - exclude: /feeds/**.xml

You can specify a browser cache expiration time for static files. To do so, provide an expiration attribute to include .... 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 loaded by the browser.

 
    static_files:
        - include: /**.png
           expiration: 4d 5h

By default, static files are served using a MIME type selected based on the filename extension. You can associate custom MIME types with filename extensions for static files in [web.xml] using <mime-mapping> elements.

Static files are served from the public_root directory. For the jruby runtime this defaults to "/public" and for other runtimes it defaults to "/". You can specify an alternate public root by putting this in app.yaml

  public_root: /static

System Properties, Environment Variables, and Context Parameters

The app.yaml file can define system properties, environment variables, and context parameters that are set when the application is running.

 
    system_properties:
        myapp.maximum-message-length: 140
        myapp.notify-every-n-signups: 1000
        myapp.notify-url: http://www.example.com/signupnotify
 
    env_variables:
        DEFAULT_ENCODING: UTF-8

    context_params:
      rack.env: production

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.

Note: Google Apps domains do not currently support HTTPS. HTTPS support is limited to apps accessed via *.appspot.com domains. Accessing an HTTPS URL on a Google Apps domain will return a "host not found" error, and accessing a URL whose handler only accepts HTTPS (see below) using HTTP will return an HTTP 403 "Forbidden" error. You can link to an HTTPS URL with the *.appspot.com domain for secure features, and use the Apps domain and HTTP for the rest of the site.

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

 
handlers:
 
- url: /youraccount/*
  login: required
  secure: always

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

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.

If you want to disallow the use of HTTPS for the application, put the following in the app.yaml file:

  ssl-enabled: false

There is no way to disallow HTTPS for some URL paths and not others in the Java runtime environment. 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.

When you test your app's HTTPS handlers using the versioned appspot.com URL, such as https://1.latest.app-id.appspot.com/, your browser will warn that the HTTPS certificate was not signed for that specific domain path. If you accept the certificate for that domain, pages will load successfully. Users will not see the certificate warning when accessing https://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. This includes handlers that specify a servlet or ones that simply add login restrictions to a URL matching another handler. When a URL handler with a login setting 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 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. You can also 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.

If not, by default, the user is redirected to the Google sign-in page, or /ah/login_required if the application is set to federated login.

If the setting is login: required, once the user has signed in, the handler proceeds normally.

If the setting is login: admin, once the user has signed in, the handler checks whether the user is an administrator for the application. If not, the user is given an error message. If the user is an administrator, the handler proceeds.

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

An example:

 
handlers:
 
- url: /profile/*
  login: required
 
- url: /admin/*
  servlet: com.example.AdminServlet
  login: admin

The Welcome File List

When the URLs for your site represent paths to static files or JSPs in your WAR, it is often a good idea for paths to directories to do something useful as well. A user visiting the URL path /help/accounts/password.jsp for information on account passwords may try to visit /help/accounts/ to find a page introducing the account system documentation. The deployment descriptor can specify a list of filenames that the server should try when the user accesses a path that represents a WAR subdirectory (that is not already explicitly mapped to a servlet). The servlet standard calls this the "welcome file list."

For example, if the user accesses the URL path /help/accounts/, the following welcome file list in app.yaml tells the server to check for help/accounts/index.jsp and help/accounts/index.html before reporting that the URL does not exist:

welcome_files:
  - index.jsp
  - index.html

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 or XMPP messages, the application must be configured to enable the service. You enable the service for a Python app by including an inbound_services section in the app.yaml file.

To enable incoming email and XMPP messages, add the following to app.yaml:

 
inbound_services:
- xmpp_message
- mail

Administration Console Custom Pages

Note: this feature is not working in the 1.3.5 SDK. It should be fixed with 1.3.6.

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

This has an inner pages: section, with an entry for each page. The name appears in the Administration Console navigation, and the url is the URL path to the page.

At this time, page names must contain only characters in the ASCII character set.

You can use configuration to restrict access to custom administration pages to only users that are administrators of the app. See Login or Administrator Status.

Enabling Sessions

App Engine includes an implementation of sessions, using the servlet session interface. The implementation stores session data in the App Engine datastore for persistence, and also uses memcache for speed. As with most other servlet containers, the session attributes that are set with session.setAttribute() during the request are saved to the datastore at the end of the request.

This feature is off by default. To turn it on, add the following to app.yaml:

 
    sessions_enabled: true

The implementation creates datastore entities of the kind _ah_SESSION, and memcache entries using keys with a prefix of _ahs.

Note: Because App Engine stores session data in the datastore and memcache, all values stored in the session must implement the java.io.Serializable interface.

Disabling Precompilation

App Engine uses a "precompilation" process with the Java bytecode of an app to enhance the performance of the app in the Java runtime environment. Precompiled code functions identically to the original bytecode.

If for some reason you prefer that your app not use precompilation, you can turn it off by adding the following to your app.yaml file:

 
  precompilation_enabled: false

Custom XML Output

If you need to use features of the Java web.xml which are not directly supported in app.yaml you may include a block of XML to be included directly into web.xml

web_xml: |
  <error-page>
    <error-code>500</error-code>
    <location>/errors/servererror.jsp</location>
  </error-page>