The App Engine Go SDK includes a web server application you can run on your computer that simulates your application running in the App Engine Go runtime environment. The simulated environment enforces some sandbox restrictions, such as restricted system functions and Go module imports, but not others, like request time-outs or quotas. The server also simulates the services by performing their tasks locally.
- Using the goapp tool
- Running the development web server
- Application IDs in the development web server
- Using the Datastore
- The Users service in the development web server
- Using Mail
- Using URL Fetch
- The Development Console
- Command-line arguments
Using the
goapp
tool
The App Engine Go SDK ships with the
goapp
tool, which is the App Engine-equivalent of the
standard
go
tool
.
The simplest way to run the development server is to invoke
goapp serve
from within the directory that contains your application's
app.yaml
configuration file:
goapp serve
For help using the tool, run
goapp help serve
for a full description of its options.
Running the development web server
Once you have a directory for your application and an
app.yaml
configuration file, you can start the development web server with the
dev_appserver.py
command:
dev_appserver.py myapp
The web server listens on port 8080 by default. You can visit the application at this URL: http://localhost:8080/ .
To change which port the web server uses, use the
--port
option:
dev_appserver.py --port=9999 myapp
To stop the web server: with Mac OS X or Unix, press Control-C or with Windows, press Control-Break in your command prompt window.
Application IDs in the development web server
If you need to access your App ID, 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.
Using the Datastore
The development web server simulates the App Engine datastore using a file on your computer. 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 local datastore for an application, use the
--clear_datastore=yes
option when you start the web server:
dev_appserver.py --clear_datastore=yes myapp
The web server prints the location of the datastore file it is using to the terminal when it starts up. You can make a copy of the file, then restore it later to reset the datastore to a known state. Be sure to restart the web server after replacing the datastore file.
To change the location used for the datastore file, use the
--datastore_path
option:
dev_appserver.py --datastore_path=/tmp/myapp_datastore myapp
When your application performs a query on the datastore, the development web server checks that the query is supported by the application's
index.yaml
file. If the query requires that its index be mentioned in the file, the server generates one and adds it to the file. You may want to edit this file if your application may attempt queries that are not exercised by your tests.
index.yaml
is generated from every query made since the datastore file was created or last cleared. The query history is stored in a separate file.
For more information on indexes and
index.yaml
, see the
Datastore Indexes
and
Datastore Index Configuration
pages.
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.
In the file-backed local datastore, the automatic IDs of all entities are drawn from a single ID sequence. In the SQLite-backed local datastore and the production datastore, a separate ID sequence is maintained for each entity group.
The default policy in the local datastore is
scattered
.
To specify the automatic ID assignment policy, use the
--auto_id_policy
option.
dev_appserver.py --auto_id_policy=scattered
The Users service in the development web server
App Engine provides a
Users Service
to simplify authentication and authorization for your application. The development web server
simulates the behavior of Google Accounts
with its own sign-in and sign-out pages. While running under the development web server, the
LoginURL
and
LogoutURL
functions return URLs for
/_ah/login
and
/_ah/logout
on the local server.
Using Mail
The development web server can send email for calls to the App Engine mail service. To enable email support, the web server must be given options that specify a mail server to use. The web server can use an SMTP server, or it can use a local installation of Sendmail .
To enable mail support with an SMTP server, use the
--smtp_host
,
--smtp_port
,
--smtp_user
and
--smtp_password
options with the appropriate values.
dev_appserver.py --smtp_host=smtp.example.com --smtp_port=25 \
--smtp_user=ajohnson --smtp_password=k1tt3ns myapp
To enable mail support with Sendmail, use the
--enable_sendmail
option with a value of
yes
. The web server will use the
sendmail
command to send email messages with your installation's default configuration.
dev_appserver.py --enable_sendmail=yes
If mail is not enabled with either SMTP or Sendmail, then attempts to send email from the application will do nothing, and appear successful in the application.
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.