Skip to page content Skip to main navigation
English | Site Directory

e.g. "templates" or "datastore"

# The Java Development Server

The App Engine Java SDK includes a development web server for testing your application on your computer. The development web server simulates the App Engine Java runtime environment and all of its services, including the datastore. The Google Plugin for Eclipse can run the server in the Eclipse debugger. You can also run the development server from the command line.

- Running the Development Web Server
- Using the Datastore
- Using Users
- Using URL Fetch
- Command-Line Arguments

## Running the Development Web Server

If you are using Eclipse and the Google Plugin, you can run the development web server in the Eclipse debugger. To run the server with the default configuration, select the Run menu, Debug As > Web Application. For more control over how the server is started, such as which port the server uses, create a new debug configuration using the configuration type "Web Application". For more information, see Google Eclipse Plugin.

You can also run the development web server from a command prompt. The command to run is in the SDK's `appengine-java-sdk/bin/` directory.

If you are using Windows, the command is as follows:

    appengine-java-sdk\bin\dev_appserver.cmd [options] war-location

If you are using Mac OS X or Linux, the command is as follows:

    appengine-java-sdk/bin/dev_appserver.sh [options] war-location

The command takes the location of your application's WAR directory as an argument.

To stop the web server, press Control-C (on Windows, Mac or Linux).

These commands are OS-specific wrapper scripts that run the Java class `com.google.appengine.tools.KickStart` in `appengine-java-sdk/lib/appengine-tools-api.jar`.

## Using the Datastore

The development web server simulates the App Engine datastore using a file on your computer. The file 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 application.)

This file 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 Configuration, the 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 `WEB-INF/` directory, using the attribute `autoGenerate="false"` for the `<datastore-indexes>` element. See Datastore Index Configuration for more information.

## Using Users

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/login` and `/_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.

## Command-Line Arguments

The development server command supports the following command-line arguments:

`--port=...`

  The port number to use for the server. Default is `8080`.

`--address=...`

  The host address to use for the server. You may need to set this to be able to access the development server from another computer on your network. An address of `0.0.0.0` allows both localhost access and hostname access. Default is `localhost`.

`--sdk_root=...`

  A path to the App Engine Java SDK, if different from the location of the tool.

`--disable_update_check`

  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.

`--help`

  Prints a helpful message then quits.