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 bundled services.
The simulated environment enforces some sandbox restrictions, such as restricted system functions and Python 2 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 using Google APIs HTTP endpoints.
Set up the local development server
To run the local development server tool, you must set up the following:
Verify that you have installed both Python interpreters on your machine:
- A Python 2 interpreter of version 2.7.12 or later
- A Python 3 interpreter that is compatible with the Python version required by the gcloud CLI
Both Python interpreters are required even if your app is written in another runtime or language version.
Verify that you have installed the gcloud component that includes the App Engine extension for Python 2 (
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
Set the
CLOUDSDK_DEVAPPSERVER_PYTHON
environment variable in your shell to the path of your Python 2 interpreter.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]
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
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 thedev_appserver.py
command.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]
To learn more about the
dev_appserver.py
command options, see Local Development Server Options.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
get_application_id()
function. To get the hostname of the running app, use the
get_default_version_hostname()
function.
Detecting 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 SERVER_SOFTWARE
environment
variable:
if os.getenv('SERVER_SOFTWARE', '').startswith('Google App Engine/'):
# Production
else:
# Local development server
Using the local Datastore
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
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 local Datastore:
Access the Datastore Viewer in the local development console. (The URL is
http://localhost:8000/datastore
.)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.
Clear the 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 local 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 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
users.create_login_url
and users.create_logout_url
functions return URLs for /_ah/login
and /_ah/logout
on the local server.
Use Mail
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 will use the sendmail
command to send email messages with
your installation's default configuration.
Use URL Fetch
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 Interactive Console
The Interactive Console allows developers to enter arbitrary Python code into a web form and execute it inside their app's environment; it provides the same access to the application's environment and services as a .py file inside the application itself.
To use the Interactive Console:
Access the Interactive console in the in the local development console. (The URL is
http://localhost:8000/console
.)Enter any Python code you'd like to run in the text area, then submit the form to execute it. For example the following code will add a Datastore entity called
Greeting
with text content ofHello
:from google.appengine.ext import ndb class Greeting(ndb.Model): content = ndb.TextProperty() e = Greeting(content="Hello") e.put()
Debug with the Python debugger
To use the Python debugger (pdb
):
Add the following line into your code:
import pdb; pdb.set_trace();
dev_appserver
will break at this point and drop into thepdb
REPL (read–eval–print loop), allowing you to debug your code from the command line.If your application makes multiple simultaneous requests that invoke
pdb.set_trace()
, multiple debugging sessions will start concurrently, each of which sends output toSTDOUT
. To avoid this, serialize your requests by disabling thedev_appserver
multi-threading and multi-processing support, as follows:Disable multi-threading for:
- All services using the
--threadsafe_override=false
flag. - One service using the
--threadsafe_override=<SERVICENAME>:false
flag. - Multiple services using the
--threadsafe_override=<SERVICE1NAME>:false,<SERVICE2NAME>:false
flag.
- All services using the
Disable multi-processing for:
- All services using the
--max_module_instances=1
flag. - One service using the
--max_module_instances=<SERVICENAME>:1
flag. - Multiple services using the
--max_module_instances=<SERVICE1NAME>:1,<SERVICE2NAME>:1
flag.
- All services using the