Using the local development server

Go Java Node.js PHP Python Ruby

Note: You can't use the latest version of dev_appserver.py to locally run your applications for runtimes that reached end of support. To continue using an archived version of dev_appserver.py, see Use the local development server after runtimes reach the end of support.

The Google Cloud 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 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

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

1. Verify that you have installed a Python 3 interpreter that is compatible with the Python version required by the gcloud CLI.

2. Verify that you have installed the Google Cloud 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
   

3. Locate the installation path of Google Cloud SDK by running the following command:

   gcloud info
   

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

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

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

   CLOUD_SDK_ROOT/bin/dev_appserver.py
   

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

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

2. The local development server is now running and listening for requests. You can visit 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.

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

• macOS or Linux: Control+C
• Windows: Control+Break

Specify application IDs

To access your App ID in the local server, for example to spoof an email address, use the appengine.AppID function.

To get the hostname of the running app, use the appengine.DefaultVersionHostname 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() method. When this is true, your code is running in the local development environment; otherwise, you're running in production.

See GitHub for an example.

Use the local Datastore service

Note: We are migrating the local development environment to use the Cloud Datastore Emulator.

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

For more information on indexes and index.yaml, see the Datastore Indexes and Datastore Index Configuration pages.

Browse the local Datastore { :#browse}

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

To browse the local Datastore:

1. Start the development server.

2. Access the Datastore Viewer in the local development console. The URL is http://localhost:8000/datastore.

3. View your local Datastore contents.

Specify the ID allocation policy

For production App Engine, you can set the Datastore to automatically generate entity IDs.

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 Datastore { :#clear_local_datastore}

To clear the local 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 Datastore location { :#change_datastore_location}

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

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

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.

Using SMTP

To enable mail support with an SMTP server, invoke dev_appserver.py as follows::

python3 [CLOUD_SDK_ROOT]/bin/dev_appserver.py --smtp_host=smtp.example.com --smtp_port=25 \
    --smtp_user=ajohnson --smtp_password=k1tt3ns [PATH_TO_YOUR_APP]

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:

python3 [CLOUD_SDK_ROOT]/bin/dev_appserver.py --enable_sendmail=yes [PATH_TO_YOUR_APP]

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 to simplify authentication and authorization for your application. The local development server simulates the behavior of Google Accounts with its own sign-in and sign-out pages.

While running under the local development server, the LoginURL and LogoutURL 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.