The App Engine Java SDK includes a command for interacting with App Engine. You can use this command to upload new versions of the code, configuration and static files for your app to App Engine. You can also use the command to manage datastore indexes and download log data.
Note: If you created your project using the Google Cloud Console, your project has a title and an id. In the instructions that follow, the project title and id can be used wherever an application title and id are mentioned. They are the same thing.
- Uploading the App
- Updating Indexes
- Deleting Unused Indexes
- Managing Task Queues
- Managing DoS Protection
- Managing Scheduled Tasks
- Downloading an Application
- Downloading Logs
- Using an HTTP Proxy
- Passwordless Login with OAuth2
- Command Line Arguments
Uploading the App
To upload your application from Eclipse, click on the Google button in the Eclipse toolbar, then select "Deploy to App Engine." For more information, see Google Eclipse Plugin .
You can also upload your application from a command prompt. To use other features of the command, such as downloading logs, you must run the command from the 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\appcfg.cmd [options] <action> <war-location>
If you are using Mac OS X or Linux, the command is as follows:
./appengine-java-sdk/bin/appcfg.sh [options] <action> <war-location>
The command takes the name of an action to perform and the location of your application's WAR directory as arguments.
To upload an application, use the
update
action, as follows:
./appengine-java-sdk/bin/appcfg.sh update myapp/war
These commands are OS-specific wrapper scripts that run the Java class
com.google.appengine.tools.admin.AppCfg
in
appengine-java-sdk/lib/appengine-tools-api.jar
.
If you are using the Modules feature, you can
upload one or more modules at a time
with the
update
command.
Troubleshooting Upload Errors
If you use the update feature with
passwordless login
,
your update attempt may fail with a message similar to this one:
404 Not Found This application does not exist (app_id=u'your-app-ID')
.
This error will occur if you have multiple Google accounts and are using the
wrong account to perform the update.
To solve this issue, change directories to
~
, locate a file
named
.appcfg_oauth2_tokens_java
, and rename it. Then try updating
again.
The App Engine Maven plugin update feature uses passwordless login by default, so this error can also be experienced when using that plugin.
Updating Indexes
When you upload an application using the
update
action, the update includes the app's index configuration
(the
datastore-indexes.xml
and
generated/datastore-indexes-auto.xml
files).
If the index configuration defines an index that doesn't exist yet on App Engine, App Engine creates the new index.
Depending on how much data is already in the datastore that needs to be mentioned in the new index, the process of creating the index may take a while.
If the app performs a query that requires an index that hasn't finished building yet, the query will raise an exception.
To prevent this, you must ensure that the new version of the app that requires a new index is not the live version of the application until the indexes finish building.
One way to do this is to give the app a new version number in
appengine-web.xml
whenever you add or change an index in the configuration.
The app is uploaded as a new version, and does not become the default version automatically.
When your indexes have finished building, you change the default version to the new one using the "Versions" section of the
Admin Console
.
Another way to ensure that new indexes are built before the new app goes live is to upload the index configuration separately before uploading the app. To upload only the index configuration for an app, use the
update_indexes
action:
./appengine-java-sdk/bin/appcfg.sh update_indexes myapp/war
You can check the status of the app's indexes from the "Indexes" section of the Admin Console .
Deleting Unused Indexes
When you change or remove an index from the index configuration, the original index is not deleted from App Engine automatically. This gives you the opportunity to leave an older version of the app running while new indexes are being built, or to revert to the older version immediately if a problem is discovered with a newer version.
When you are sure that old indexes are no longer needed, you can delete them from App Engine using the
vacuum_indexes
action:
./appengine-java-sdk/bin/appcfg.sh vacuum_indexes myapp/war
This command deletes all indexes for the app that are not mentioned in the local versions of
datastore-indexes.xml
and
generated/datastore-indexes-auto.xml
.
Managing Task Queues
You define and configure task queues in a file called
queue.xml
. You can upload this configuration separately from the rest of the app using the
update_queues
command:
./appengine-java-sdk/bin/appcfg.sh update_queues myapp/war
appcfg update
will also upload task queue configuration if the file exists.
For more on task queues, see the Task Queues documentation.
Managing DoS Protection
You configure DoS protection for an app in a file called
dos.xml
. You can upload this configuration separately from the rest of the app using the
update_dos
command:
./appengine-java-sdk/bin/appcfg.sh update_dos myapp/war
appcfg update
will also upload DoS protection configuration if the file exists.
Managing Scheduled Tasks
App Engine supports scheduled tasks (known as cron jobs). You specify these in a file called
cron.xml
, and upload them using the
update_cron
command:
./appengine-java-sdk/bin/appcfg.sh update_cron myapp/war
appcfg update
will also upload cron job specifications if the file exists.
You can also verify your cron configuration from the command line using the
cron_info
action:
./appengine-java-sdk/bin/appcfg.sh cron_info myapp/war
For more on cron jobs, see the Cron Jobs documentation.
Downloading an Application
You can download an application by running appcfg.sh with the
download_app
action in the Java SDK command line tool:
./appengine-java-sdk/bin/appcfg.sh -A <your_app_id> -V <your_app_version> download_app <output-dir>
This command downloads your compiled application in the WAR that you uploaded most recently.
Output like the following results if the command is successful:
0% Fetching files... 0% [1/13] WEB-INF/lib/appengine-api-labs-1.2.6.jar 7% [2/13] WEB-INF/appengine-web.xml 14% [3/13] WEB-INF/lib/datanucleus-jpa-1.1.5.jar 21% [4/13] WEB-INF/lib/datanucleus-core-1.1.5.jar 28% [5/13] WEB-INF/lib/datanucleus-appengine-1.0.3.jar 35% [6/13] WEB-INF/lib/jdo2-api-2.3-eb.jar 42% [7/13] WEB-INF/classes/com/example/MyServlet.class 50% [8/13] WEB-INF/lib/geronimo-jpa_3.0_spec-1.1.1.jar 64% [9/13] WEB-INF/lib/geronimo-jta_1.1_spec-1.1.1.jar 71% [10/13] testlogin.html 78% [11/13] WEB-INF/web-bck.xml 85% [12/13] WEB-INF/web.xml 92% [13/13] __static__/testlogin.html download_app completed successfully.
Only the developer who uploaded the app can download it. If anyone other than that developer attempts to download the app, they'll receive an error message.
You can permanently disable app downloads from the Versions screen in your development web server. On that page, click permanently prohibit code downloads :
Warning! This action is irreversible. After you prohibit code download, there is no way to re-enable this feature.
Downloading Logs
App Engine maintains a log of messages that your application emits. App Engine also records each request in the log. Each request is assigned a request ID , a globally unique identifier based on the request's start time. Each log level has a fixed buffer size that controls the amount of log information you can access. Normally, you use logging features more at lower log levels; thus, the time window is smaller for log events at these levels. You can browse your app's logs of the last 90 days from the "Logs" section of the Admin Console .
If you wish to perform more detailed analysis of your application's logs, you can download the log data to a file on your computer.
To download logs to a file named
mylogs.txt
, use the
request_logs
action, as follows:
./appengine-java-sdk/bin/appcfg.sh request_logs myapp/war mylogs.txt
By default, the command downloads log messages from the current calendar day (since midnight Pacific Time) with a log level of INFO or higher (omitting DEBUG level messages). You can adjust the number of days, the minimum log level, and whether to overwrite or append to the local log file using command line options.
By default, the command overwrites the local log file. You can tell it to append the downloaded data to the file instead by specifying the
--append
argument.
This simply appends the requested log data to the file, it doesn't guarantee that the file doesn't contain duplicate log messages.
Using an HTTP Proxy
If your development environment resides behind an HTTP proxy, the AppCfg command needs to know about the proxy to connect to App Engine.
To tell AppCfg about your proxy, using the
--proxy
option:
./appengine-java-sdk/bin/appcfg.sh --proxy=10.1.2.3 update myapp/war
If you use a different proxy for HTTPS, you can specify it using the
--proxy_https
option.
Passwordless Login with OAuth2
If you don't want to enter your login credentials, you can use an OAuth2 token instead. This token gives access to App Engine, but not to other parts of your Google account; if your Google account uses two-factor authentication , you'll find this especially convenient. You can store this token to permanently log in on this machine.
To set this up, use the
--oauth2
option.
This will store your
OAuth2
credentials in your home directory in a file called
.appcfg_oauth_tokens_java
.
If you don't want to permanently log in by storing your OAuth2 token
on disk, also use the
--no_cookies
option.
./appengine-java-sdk/bin/appcfg.sh --oauth2 update myapp/war
A page will appear in your web browser prompting you for authentication. If no browser could be started, then
appcfg.sh
will instead show you a URL to copy/paste into your
browser. Log in if necessary. The page will ask whether you wish to
give appcfg access. Click OK, then you will be given a token that you will need to supply to the prompt from
appcfg.sh
.
From now on, when you run
./appengine-java-sdk/bin/appcfg.sh --oauth2
, it
uses the saved authentication token.
Command Line Arguments
The AppCfg command takes a set of options, an action, and arguments for the action.
The following actions are available:
-
appcfg.sh [options] update <app-directory> | <files...>
-
If you specify an app-directory, it must contain of the files required by the app. The update command creates or updates the app version named in the app.yaml file at the top level of the directory. It follows symlinks and recursively uploads all files to the server. Temporary or source control files (e.g. foo~, .svn/*) are skipped.
If you are using the Modules feature, you can upload one or more modules at a time with the
update
command. -
appcfg.sh [options] cron_info <app-directory>
-
Verifies and prints the scheduled task (cron) configuration.
-
appcfg.sh -A <app_id> -V <version> download_app <output-dir>
-
Retrieves the most current version of your application using the following options:
-
-A
-
The application ID (required).
-
-V
-
The current application version. May be one of the following:
-
-V major.minor
– Specifies the exact version specified. -
-V major
– Specifies the latest major version. - Omitted entirely – Returns the current default version, if one exists
-
-
<output-dir>
-
The directory where you wish to save the files (required).
-
-
appcfg.sh [options] request_logs <war-location> <output-file>
-
Retrieves log data for the application running on App Engine.
output-file
is the name of the file to create or replace. Ifoutput-file
is a hyphen (-
), the log data is printed to the console. The following options apply torequest_logs
:-
--num_days= ...
-
The number of days of log data to retrieve, ending on the current date at midnight UTC. A value of 0 retrieves all available logs. If
--append
is given, then the default is 0, otherwise the default is 1. -
--severity= ...
-
The minimum log level for the log messages to retrieve. The value is a number corresponding to the log level: 4 for CRITICAL, 3 for ERROR, 2 for WARNING, 1 for INFO, 0 for DEBUG. All messages at the given log level and above will be retrieved. Default is 1 (INFO).
-
--append
-
Tells AppCfg to append logs to the log output file instead of overwriting the file. This simply appends the requested data, it does not guarantee the file won't contain duplicate error messages. If this argument is not specified, AppCfg will overwrite the log output file.
-
-
appcfg.sh [options] help <action>
-
Prints a help message about the given action, then quits.
-
appcfg.sh [options] version
-
Prints detailed version information about the SDK, Java and the operating system, then quits. Use this when submitting bug reports.
-
appcfg.sh [options] rollback <war-location>
-
Undoes a partially completed update for the given application. You can use this if an update was interrupted, and the command is reporting that the application cannot be updated due to a lock.
-
appcfg.sh [options] update <war-location>
-
Uploads files for an application given the application's root directory. The application ID and version are taken from the
appengine-web.xml
file. -
appcfg.sh [options] update_cron <app-directory>
-
Updates the schedule task (cron) configuration for the app, based on the
cron.xml
file. -
appcfg.sh [options] update_dos <app-directory>
-
Updates the DoS protection configuration for the app, based on the
dos.xml
file. -
appcfg.sh [options] update_indexes <war-location>
-
Updates datastore indexes in App Engine to include newly added indexes. If a new version of your application requires an additional index definition that was added to the index configuration, you can update your index configuration in App Engine prior to uploading the new version of your application. Running this action a few hours prior to uploading your new application version will give the indexes time to build and be serving when the application is deployed.
-
appcfg.sh [options] update_queues <war-location>
-
Updates the task queue configuration (
queue.xml
) in App Engine. If the new configuration does not include a named queue (other thandefault
) that exists and has tasks, the existing queue is paused. -
appcfg.sh [options] start <war-location>
-
Start the specified module version.
-
appcfg.sh [options] stop <war-location>
-
Stop the specified module version.
The AppCfg command accepts the following options for all actions:
-
--email= ...
-
The email address of the Google account of an administrator for the application, for actions that require signing in. If omitted and no cookie is stored from a previous use of the command, the command will prompt for this value.
-
--server= ...
-
The App Engine server hostname. The default is
appengine.google.com
. -
--host= ...
-
The hostname of the local machine for use with remote procedure calls.
-
--sdk_root= ...
-
A path to the App Engine Java SDK, if different from the location of the tool.
-
--no_cookies
-
Do not store the administrator sign-in credentials. Prompt for a password every time. (or go through the OAuth2 flow when the
--oauth2
option is used). -
--passin
-
Do not store the administrator sign-in credentials as a cookie; prompt for a password every time.
-
--proxy=...
-
Use the given HTTP proxy to contact App Engine.
-
--proxy_https=...
-
Use the given HTTPS proxy to contact App Engine, when using HTTPS. If
--proxy
is given but--proxy_https
is not, both HTTP and HTTPS requests will use the given proxy. -
--oauth2
-
Use OAuth2 authentication instead of password-based authentication.