The original App Engine architecture is based on a single frontend instance with optional backend instances. If you plan to use modules with an existing app, you will need to migrate your frontend so it is handled as a module. You may also want to convert any existing backends to module format to take full advantage of the additional functionality that modules provide (like the ability to version backends). This page describes both processes.

1. Migrating an existing frontend to Modules
2. Converting backends to Modules

Migrating an existing frontend to Modules

When you run an app with a single (non-module) frontend instance, you use the Admin Console to customize the frontend performance settings. The settings are found on the Administration>Application Settings page, in a section named Performance . The frontend performances settings are:

• Frontend instance class
• Min/Max Idle Instances
• Min/Max Pending Latency

With the advent of modules, the frontend is treated like any other module; its performance settings are included in its xml file.

Before you can start using modules in an existing app, the frontend settings must be migrated to module settings. After migrating, your frontend instances are managed as modules with the same settings. There are two ways that migration can happen:

Automatic migration

If you have not specified any custom frontend settings, migration occurs automatically the first time you upload any module. You don’t need to take any special action.

Manual migration

If you’ve changed any of the frontend performance settings, you can’t upload module files until you’ve migrated manually. A section titled Performance Settings Migration for Modules appears in the Admin Console below the Performance section. This section displays code snippets that define an automatic-scaling module with performance settings equivalent to the current frontend. You can copy this code and use it to redefine your original frontend source file as a module. Press Migrate Settings to perform the migration. The app continues to run and you can now upload modules.

Once you’ve migrated the frontend, the performance settings will no longer appear in the Admin Console.

Migration is not reversible. After you have migrated, you should define and deploy app components as modules. If you upload an old-style xml config file without a <module> tag, it will become the new default module.

Converting backends to Modules

If you have an existing application that uses backends, App Engine automatically runs each backend as a new, non-default version of the default module. Resident backends are assigned manual scaling and dynamic backends are assigned basic scaling.

You can convert backend instances to named modules that are versioned and have explicit scaling type and instance classes. You must replace the original backends.xml file with multiple WAR files, one for each module. The procedure is as follows:

1. Create a top level EAR directory.
2. Create a META-INF subdirectory in the EAR directory that contains an appengine-application.xml file and an application.xml file.
3. Add module declaration elements to the appengine-application.xml file.
4. Create a subdirectory in the EAR directory for each module in the app including the default module. By convention, each subdirectory has the same name as the module it defines.
5. Copy the contents of the original WAR directory into each subdirectory. The original WAR should have a subdirectory named WEB-INF . Each new subdirectory must have its own copy of that directory.
6. Add module configuration elements (to define module name, scaling, instance class, etc.) to the appengine-web.xml files in each subdirectory.
7. Application configuration files ( cron.xml , dispatch.xml , dos.xml , etc.) should only be included in the default module subdirectory. Remove these files from all the other module subdirectories.

For example, here is a file example/backends.xml that defines three backends ( memdb , worker , and cmdline ):

<backends>
 <backend name="memdb">
   <class>B8</class>
   <instances>5</instances>
 </backend>
 <backend name="worker">
   <options>
     <fail-fast>true</fail-fast>
   </options>
 </backend>
 <backend name="cmdline">
   <options>
     <dynamic>true</dynamic>
   </options>
 </backend>
</backends>

To convert these backends to modules, first assume you've created a new EAR directory called "ear." Declare the backends as modules in the file ear/META-INF/application.xml . Notice that this file also declares the default module as well:

<?xml version="1.0" encoding="UTF-8"?>
<application
  xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
                      http://java.sun.com/xml/ns/javaee/application_5.xsd"
  version="5">

  <description>Demo Application</description>
  <display-name>My Java App</display-name>

  <!-- Default Module -->
  <module>
    <web>
      <web-uri>default</web-uri>
      <context-root>defaultcontextroot</context-root>
    </web>
  </module>
  <!-- Other Modules -->
  <module>
    <web>
      <web-uri>memdb</web-uri>
      <context-root>memdb</context-root>
    </web>
  </module>
  <module>
    <web>
      <web-uri>worker</web-uri>
      <context-root>worker</context-root>
    </web>
  </module>
  <module>
    <web>
      <web-uri>cmdline</web-uri>
      <context-root>cmdline</context-root>
    </web>
  </module>
</application>

The configuration for each module is written in a separate appengine-web.xml file, under the corresponding subdirectory. In ear/memdb/WEB-INF/appengine-web.xml :

<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>my-java-app</application>
  <module>memdb</module>
  <version>uno</version>
  <threadsafe>true</true>
  <instance-class>F4</instance-class>
  <manual-scaling>
    <instances>5</instances>
  </manual-scaling>
</appengine-web-app>

In ear/worker/WEB-INF/appengine-web.xml :

// ear/worker/WEB-INF/appengine-web.xml
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>my-java-app</application>
  <module>worker</module>
  <version>uno</version>
  <threadsafe>true</threadsafe>
   <!-- For failfast functionality, please use the ‘X-AppEngine-FailFast’ header on requests made to this module. -->
  <instance-class>F2</instance-class>
  <manual-scaling>
    <instances>5</instances>
  </manual-scaling>
</appengine-web-app>

In ear/cmdline/WEB-INF/appengine-web.xml :

<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>my-java-app</application>
  <module>cmdline</module>
  <version>uno</version>
  <threadsafe>true</threadsafe>
  <instance-class>F2</instance-class>
  <basic-scaling>
    <max-instances>10?</max-instances>
  </basic-scaling>
</appengine-web-app>

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License , and code samples are licensed under the Apache 2.0 License . For details, see our Site Policies .