The App Engine SDK for Java includes a local development server for testing your application on your computer. The local development server simulates the App Engine Java runtime environment and all of its services, including Datastore.
Running the Development Web Server
For information about setting your system properties and environment variables for your app, see How Requests are Handled.
You can also run the development web server from a command prompt. The command
to run is in the SDK's
Windows command syntax:
appengine-java-sdk\bin\dev_appserver.cmd [options] [WAR_DIRECTORY_LOCATION]
Mac OS X or Linux command syntax:
appengine-java-sdk/bin/dev_appserver.sh [options] [WAR_DIRECTORY_LOCATION]
The command takes the location of your application's WAR directory as an argument.
To stop the web server, press Ctrl-C.
These commands are OS-specific wrapper scripts that run the Java class
Using the local Datastore emulator
The development web server simulates Datastore using a local file-backed
Datastore on your computer. The Datastore is named
local_db.bin, and it is
created in your application's WAR directory, in the
WEB-INF /appengine-generated/ directory. It is not uploaded with your
This Datastore persists between invocations of the web server, so data you store will still be available the next time you run the web server. To clear the contents of the Datastore, shut down the server, then delete this file.
As described in Datastore Index
development server can generate configuration for Datastore indexes needed by
your application, determined from the queries it performs while you are testing
it. This generates a file named
datastore-indexes-auto.xml in the directory
WEB-INF/appengine-generated/ in the WAR. To disable automatic index
configuration, create or edit the
datastore-indexes.xml file in the
directory, using the attribute
autoGenerate="false" for the
<datastore-indexes> element. For more information, see
Datastore Index Configuration.
Browsing Datastore in the development server
To browse your local Datastore using the development web server:
- Start the development server as described previously.
- Go to the Development Console.
- Click Datastore Viewer in the left navigation pane to view your local Datastore contents.
The High Replication Datastore Consistency Model
By default, the local Datastore is configured to simulate the consistency model of the High Replication Datastore, with the percentage of Datastore writes that are not immediately visible in global queries set to 10%.
To adjust this level of consistency, set the
datastore.default_high_rep_job_policy_unapplied_job_pct system property with a
value corresponding to the amount of eventual consistency you want your
application to see.
If you are setting this property using the command prompt
you need to use
--jvm_flag=... to set the property:
The valid range for
between 0 and 100. If you use numbers outside of this range, you will receive
If you're using
you can pass this flag as an argument to
appengine:devserver using the
<jvmFlags> <jvmFlag>-Ddatastore.default_high_rep_job_policy_unapplied_job_pct=20</jvmFlag> </jvmFlags>
Specifying the Automatic ID Allocation Policy
You can configure how the local Datastore assigns automatic entity IDs. The following automatic ID allocation policies are supported in the development server:
- IDs are assigned from the sequence of consecutive integers.
- IDs are assigned from a non-repeating sequence of approximately uniformly distributed integers.
The default policy in the local Datastore is
To specify the automatic ID policy, set the
datastore.auto_id_allocation_policy system property to either
To set this system property through a flag passed to the dev_appserver macro:
The development web server simulates Google Accounts with its own sign-in and
sign-out pages. While running under the development web server, the methods
that generate sign-in and sign-out URLs return URLs for
/_ah/logout on the local server.
The development sign-in page includes a form where you can enter an email address. Your session uses whatever email address you enter as the active user.
To have the application believe that the logged-in user is an administrator, check the "Sign in as Administrator" checkbox on the form.
Using URL Fetch
When your application uses the URL Fetch API to make an HTTP request, the development web server makes the request directly from your computer. The behavior may differ from when your application runs on App Engine if you use a proxy server for accessing websites.
The Development Console
The development web server includes a console web application. With the console you can browse the local Datastore.
To access the console, visit the URL
/_ah/admin on your server:
The development server command supports the following command-line arguments:
The host address to use for the server. You might need to set this to be able to access the development server from another computer on your network. An address of
0.0.0.0allows both localhost access and hostname access. Default:
Set the default Google Cloud Storage bucket name.
If given, the development server will not contact App Engine to check for the availability of a new release of the SDK. By default, the server checks for a new version on start-up, and prints a message if a new version is available.
Set the directory where generated files are created.
Prints a helpful message then quits.
Pass the given flag as a JVM argument. Can be repeated to supply multiple flags.
The port number to use for the server. Default is
A path to the App Engine Java SDK, if different from the location of the tool.
The server to use to determine the latest SDK version.