using local server

Using the local development server

The local development server is not supported for this runtime. To test your application before deploying, run your application in your local environment with the development tools that you usually use.

Note: You can't use the latest version of dev_appserver.py to locally run your applications for runtimes that reached end of support.

The gcloud CLI for Java includes a local development server for testing your application on your computer. The local development server emulates the App Engine Java runtime environment and all of its services, including Datastore.

Warning: The standalone SDK is shut down and the local development server commands have changed. The instructions below assume you have installed gcloud CLI.

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 google-cloud-sdk/bin/ directory.

Windows command syntax:

google-cloud-sdk\bin\java_dev_appserver.cmd [options] [WAR_DIRECTORY_LOCATION]

Linux or macOS command syntax:

google-cloud-sdk/bin/java_dev_appserver.sh [options] [WAR_DIRECTORY_LOCATION]

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

Stopping the development server

To stop the web server, press Ctrl-C.

Detecting the application runtime environment

To determine whether your code is running in production or in the local development server, you can check the value of the SystemProperty.environment.value() method. For example:

if (SystemProperty.environment.value() == SystemProperty.Environment.Value.Production) {
   // Production
 } else {
  // Local development server
  // which is: SystemProperty.Environment.Value.Development
}

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 application.

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 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.

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 Cloud Datastore consistency model

By default, the local Datastore is configured so that 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.

-Ddatastore.default_high_rep_job_policy_unapplied_job_pct=20

If you are setting this property using the command prompt java_dev_appserver.sh, you need to use --jvm_flag=... to set the property:

google_cloud_sdk/bin/java-dev_appserver.sh  --jvm_flag=-Ddatastore.default_high_rep_job_policy_unapplied_job_pct=20

The valid range for datastore.default_high_rep_job_policy_unapplied_job_pct is between 0 and 100. If you use numbers outside of this range, you will receive an error.

Note: If you require strong consistency for your query results, you need to use an ancestor query limiting the results to a single entity group. For more information, see Structuring data for strong consistency.

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:

sequential : IDs are assigned from the sequence of consecutive integers.

scattered : IDs are assigned from a non-repeating sequence of approximately uniformly distributed integers.

Note: The auto ID assignment policies for the production server are completely different than those used by the development server. The default production server policy is similar to the scattered policy but not the same. There is no policy that corresponds to sequential. Your app should make no assumptions about the sequence of automatic IDs assigned in production.

The default policy in the local Datastore is scattered.

To specify the automatic ID policy, set the datastore.auto_id_allocation_policy system property to either sequential or scattered.

-Ddatastore.auto_id_allocation_policy=scattered

To set this system property through a flag passed to the dev_appserver macro:

java_dev_appserver --jvm_flag=-Ddatastore.auto_id_allocation_policy=scattered

Simulating User Accounts

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.

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: http://localhost:8080/_ah/admin

Command-Line Arguments

For the local development server command options, see here.

Note: You can't use the latest version of dev_appserver.py to locally run your applications for runtimes that reached end of support.

The gcloud CLI includes a local development server (dev_appserver.py). You can use the local development server to simulate running your App Engine application in production as well as use it to access App Engine legacy bundled services. The simulated environment enforces some sandbox restrictions, such as restricted system functions and runtime language module imports, but not others, like request timeouts or quotas.

The local development server also simulates the services provided by the libraries in the SDK for App Engine, including Cloud Datastore, Memcache, and Task Queues, by performing their tasks locally. When your application is running in the development server, you can still make remote API calls to the production infrastructure by using the Google API HTTP endpoints.

Set up the local development server

Note: The dev_appserver tool does not support development of Python 3 apps on Windows.

To run the local development server tool, you must set up the following:

Verify that you have installed a Python 3 interpreter that is compatible with the Python version required by the gcloud CLI.
Verify that you have installed the gcloud CLI component that includes the App Engine extension for Python 3 (app-engine-python):

gcloud components list

If the app-engine-python component is not installed, run the following command:

gcloud components install app-engine-python

Locate the installation path of Google Cloud CLI by running the following command:

gcloud info

The command returns the root directory where you installed Google Cloud CLI, for example:

Installation Root: [/Users/myname/google-cloud-sdk]

Locate the dev_appserver.py tool under the /bin/ folder where you installed gcloud CLI, for example:

*CLOUD_SDK_ROOT*/bin/dev_appserver.py

Note the path to the dev_appserver.py for later.

Run the local development server

After setting up the local development server and creating the app.yaml configuration file for your app, you can use the dev_appserver.py command to run your app locally.

To start the local development server:

In the directory that contains your `app.yaml` configuration file, run the `dev_appserver.py` command.

{dev_appserver.py} Specify the directory path to your app, for example:

python3 *CLOUD_SDK_ROOT*/bin/dev_appserver.py *PATH_TO_YOUR_APP*

   Alternatively, you can specify the configuration file of a specific

service, for example:

python3 *CLOUD_SDK_ROOT*/bin/dev_appserver.py app.yaml

To change the port, you include the --port option:

python3 *CLOUD_SDK_ROOT*/bin/dev_appserver.py --port=9999 *PATH_TO_YOUR_APP*

{goapp serve}

 The `goapp serve` command is included with the original
 App Engine SDK for Go and wraps the underlying
 `dev_appserver.py` Python tool. To start the local development server,
 you run:

 ```
 goapp serve
 ```

In the directory that contains your `app.yaml` configuration file, run the `dev_appserver.py` command.

{Windows / macOS} Specify the directory path to your app, for example:

python3 *CLOUD_SDK_ROOT*/bin/dev_appserver.py *PATH_TO_YOUR_APP*

   Alternatively, you can specify the configuration file of a specific

service, for example:

python3 *CLOUD_SDK_ROOT*/bin/dev_appserver.py app.yaml

To change the port, you include the --port option:

python3 *CLOUD_SDK_ROOT*/bin/dev_appserver.py --port=9999 *PATH_TO_YOUR_APP*

   Note: The SDKs for macOS and Windows already include binaries for the
   PHP runtime so there is no need to separately install
   PHP.

{Linux / cust. php-cgi} If you're on Linux or if you want to use a custom version of php-cgi, you need to specify the directory path to the php-cgi:

<ol><li>Build your own version of [App Engine PHP Extension](https://github.com/GoogleCloudPlatform/appengine-php-extension)
   on your local machine.

</li><li>Start the local development server with both the
   `--php_executable_path` and `--php_gae_extension_path` options:

 ```
 python3 *CLOUD_SDK_ROOT*/bin/dev_appserver.py --php_executable_path=[PATH_TO_PHP_7_EXECUTABLE] --php_gae_extension_path=[PATH_TO_APPENGINE_EXTENSION] app.yaml
 ```

 where `--php_executable_path` is the location of the PHP
 interpreter you are using, and where `--php_gae_extension_path` is
 the location of the `gae_runtime_module.so` file that you built in
 the previous step.
</li></ol>

In the directory that contains your `app.yaml` configuration file, run the `dev_appserver.py` command.

Specify the directory path to your app, for example:

Alternatively, you can specify the configuration file of a specific service, for example:

python3 *CLOUD_SDK_ROOT*/bin/dev_appserver.py app.yaml

To change the port, you include the --port option:

[PATH_TO_YOUR_APP] ```

</li>

<li> The local development server is now running and listening for requests. You
can visit [http://localhost:8080/](http://localhost:8080/) in your web browser
to see the app in action.

If you specified a custom port with the `--port` option, remember to open your
browser to that port.

</li></ol>

To stop the local server from the command line, press the following:

* macOS or Linux: <kbd>Control+C</kbd>
* Windows: <kbd>Control+Break</kbd>

## Specify application IDs

To access your App ID in the local server, for example to spoof an email
address, use the
[`appengine.AppID`](https://cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest#google_golang_org_appengine_v2_AppID)
function.

To get the hostname of the running app, use the
[`appengine.DefaultVersionHostname`](https://cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest#google_golang_org_appengine_v2_DefaultVersionHostname)
function.

To access your App ID in the local server, for example to spoof an email
address, use the
[`AppIdentityService::getApplicationId`](https://googlecloudplatform.github.io/appengine-php-sdk/2.1.0/Google/AppEngine/Api/AppIdentity/AppIdentityService.html#method_getApplicationId)
function.

To get the hostname of the running app, use the
[`AppIdentityService::getDefaultVersionHostname`](https://googlecloudplatform.github.io/appengine-php-sdk/2.1.0/Google/AppEngine/Api/AppIdentity/AppIdentityService.html#method_getDefaultVersionHostname)
function.

To access your App ID in the local server, for example to spoof an email
address, use the
[`get_application_id()`](https://cloud.google.com/appengine/docs/standard/python3/reference/services/bundled/google/appengine/api/app_identity/get_application_id)
function.

To get the hostname of the running app, use the
[`get_default_version_hostname()`](https://cloud.google.com/appengine/docs/standard/python3/reference/services/bundled/google/appengine/api/app_identity/get_default_version_hostname)
function.

## Detect application runtime environment

To determine whether your code is running in production or in the local
development server, you can call the
[`IsDevAppServer()`](https://cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest#google_golang_org_appengine_v2_IsDevAppServer)
method. When this is `true`, your code is running in the local development
environment; otherwise, you're running in production.

See
[GitHub](https://github.com/GoogleCloudPlatform/golang-samples/blob/main/docs/appengine/tools/devserver/devserver.go
) for an example.

To determine whether your code is running in production or in the local
development server, you can check the value of the `SERVER_SOFTWARE` environment
variable:

    if (strpos(getenv('SERVER_SOFTWARE'), 'Development') === 0){
      echo 'Local development server';
    } else {
      echo 'Production';
    }

## Debug locally with XDebug

For PHP, if you have a debugger that is compatible with the [XDebug
debugger](http://xdebug.org/), and you have the `xdebug` module installed, you
can use XDebug with the local development server.

To enable XDebug on the Development Server on Linux or macOS:

1. Export the `XDEBUG_CONFIG` environment variable with an idekey for your IDE to
connect to

        export XDEBUG_CONFIG="idekey=netbeans-xdebug remote_host=localhost"

2. Invoke the Development Server with `--php_remote_debugging=yes`

To determine whether your code is running in production or in the local
development server, you can check the value of the `GAE_ENV` environment
variable:

    if os.getenv('GAE_ENV', '').startswith('standard'):
      # Production in the standard environment
    else:
      # Local development server

## Use the local Cloud Datastore service

Note: We are migrating the local development environment to use the [Cloud Cloud
Datastore
Emulator](https://cloud.google.com/datastore/docs/tools/datastore-emulator).

The local development server simulates the App Engine Cloud Datastore using a
local file that persists between invocations of the local server.

For more information on indexes and `index.yaml`, see the [Cloud Datastore
Indexes](../../configuring-datastore-indexes-with-index-yaml) page.

### Browse the local Cloud Datastore

If your app has written data to your local Cloud Datastore using the local
development server, you can browse it in the local development console.

To browse the local Cloud Datastore:

1. [Start the development server](#running_the_local_development_server).

2. Access the [Cloud Datastore Viewer](http://localhost:8000/datastore) in the
local development console. The URL is `http://localhost:8000/datastore`.

3. View your local Cloud Datastore contents.

### Specify the ID allocation policy

For production App Engine, you can set the Cloud Datastore to [automatically
generate entity
IDs](https://cloud.google.com/appengine/docs/standard/go/datastore/creating-entity-keys#Assigning_identifiers).

Although the auto ID assignment policies for the production server are
completely different than those used by the development server, you can also set
the automatic ID allocation policy for the local server.

To specify the automatic ID assignment policy, use the `--auto_id_policy`
option:

      python3 *CLOUD_SDK_ROOT*/bin/dev_appserver.py --auto_id_policy=sequential

where `--auto_id_policy` can be one of the following:

- `scattered`: (default) IDs are assigned from a non-repeating sequence of
    approximately uniformly distributed integers.
- `sequential`: IDs are assigned from the sequence of consecutive integers.

Note: Your app should make no assumptions about the sequence of automatic IDs
assigned in production. .

### Clear the local Cloud Datastore

To clear the local Cloud Datastore for an application, invoke the local
development server as follows:

    python3 *CLOUD_SDK_ROOT*/bin/dev_appserver.py --clear_datastore=yes app.yaml

### Change the local Cloud Datastore location

To change the location used for the Cloud Datastore file, use the
`--datastore_path` option:

    python3 *CLOUD_SDK_ROOT*/bin/dev_appserver.py --datastore_path=/tmp/myapp_datastore app.yaml

App Engine supports [reading and writing to Cloud
Storage](https://cloud.google.com/appengine/docs/standard/php/googlestorage/)
via PHP's streams API. You can read and write to Cloud Storage by specifying a
Cloud Storage URI (`gs://`) when using any PHP function that supports PHP
Streams implementation such as [fopen](http://php.net/manual/en/function.fopen),
[fwrite](http://php.net/manual/en/function.fwrite) or
[file_get_contents](http://php.net/manual/en/function.file-get-contents).

The local development server emulates this functionality by reading and writing
to temporary local files that are preserved between requests.

### Browse the local Cloud Datastore

If your app has written data to your local Cloud Datastore using the local
development server, you can browse it in the local development console.

To browse the local Cloud Datastore:

1. [Start the development server](#running_the_local_development_server).

2. Access the [Cloud Datastore Viewer](http://localhost:8000/datastore) in the
local development console. (The URL is `http://localhost:8000/datastore`.)

3. View your local Cloud Datastore contents.

## Use the Mail service

The local development server can send email for calls to the App Engine mail
service using either an SMTP server or a local installation of
[Sendmail](http://www.sendmail.org/).

* {Using SMTP}
    To enable mail support with an SMTP server, invoke `dev_appserver.py` as
    follows::

    where you set the `--smtp_host`, `--smtp_port`, `--smtp_user` and
    `--smtp_password` options with your own values.

* {Using Sendmail}
    To enable mail support with Sendmail, invoke `dev_appserver.py` as follows:

    The local server uses the `sendmail` command to send email messages with
    your installation's default configuration.

    Note: If you don't invoke `dev_appserver.py` with either SMTP or Sendmail as
    described, then attempts to send email from your application will do
    nothing, but the attempt will appear successful in your application.

## Use the URL Fetch service

When your application uses the URL fetch API to make an HTTP request, the local
development server makes the request directly from your computer.  The URL Fetch
behavior on the local server may differ from production App Engine if you use a
proxy server for accessing websites.

## Use the Users service

App Engine provides a [Users service](../../index) to simplify authentication
and authorization for your application. The local development server [simulates
the behavior of Google
Accounts](../../index#Google_accounts_and_the_development_server) with its
own sign-in and sign-out pages.

While running under the local development server, the
[`LoginURL`](https://cloud.google.com/appengine/docs/standard/go/users/reference#LoginURL)
and
[`LogoutURL`](https://cloud.google.com/appengine/docs/standard/go/users/reference#LogoutURL)
functions return URLs for `/_ah/login` and `/_ah/logout` on the local server.

While running under the local development server, the
[`createLoginURL`](https://cloud.google.com/appengine/docs/standard/php/refdocs/classes/google.appengine.api.users.UserService#method_createLoginURL)
and
[`createLogoutURL`](https://cloud.google.com/appengine/docs/standard/php/refdocs/classes/google.appengine.api.users.UserService#method_createLogoutURL)
functions return URLs for `/_ah/login` and `/_ah/logout` on the local server.

While running under the local development server, the functions return URLs for
`/_ah/login` and `/_ah/logout` on the local server.

## Command-line arguments

For the local development server command options, see [Local development server
options](../../local-devserver-command).

using local server

Using the local development server

Running the Development Web Server

Stopping the development server

Detecting the application runtime environment

Using the local Datastore emulator

Browsing Datastore in the development server

The Cloud Datastore consistency model

Specifying the Automatic ID Allocation Policy

Simulating User Accounts

Using URL Fetch

The Development Console

Command-Line Arguments

Set up the local development server

Run the local development server

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!