grunt-gae

Google App Engine management plugin for Grunt.

grunt-gae

Google App Engine management plugin for Grunt.

This plugin provides a way to execute dev_appserver.py and appcfg.py commands via a Grunt interface.

Due to its generic nature and support for custom arguments it always stays up to date with latest version of Google App Engine SDK and provides its full functionality.

Some of the possible applications are:

  • Starting (also asynchronously) and stopping a local GAE development server
  • Deploying your app to Google App Engine
  • Deploying to a specific, custom version
  • Updating indexes
  • Deleting unused indexes
  • Updating Task Queue configuration
  • Updating the DoS protection configuration
  • Managing scheduled tasks

It comes especially handy in conjunction with other Grunt tasks. For example, you can specify to deploy to dev.your-app.appspot.com each time a debug build of your code scceeds while deploying to the default your-app.appspot.com when your production build is complete.

This plugin requires Grunt ~0.4.1 and Google App Engine SDK.

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-gae --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-gae');

Google App Engine SDK can be downloaded from Google App Engine Downloads page.

In your project's Gruntfile, add a section named gae to the data object passed into grunt.initConfig().

grunt.initConfig({
  gae: {
    options: {
      // Task-specific options go here. 
    },
    your_target: {
      action: 'action name',
      options: {
        // Target-specific options go here. 
      }
    },
  },
})

The action property specifies the Google App Engine task to run. grunt-gae supports all actions that appcfg.py does plus two custom actions: run and kill.

Special action. Runs local Google App Engine development server.

Special action. Kills local Google App Engine development server if started asynchronously.

Deploys the app to Google App Engine.

Updates indexes.

Deletes unused indexes.

Updates Task Queue configuration

Updates the DoS protection configuration

Manages scheduled tasks specified in cron.yaml

Type: String Default value: '.' Required: yes

Path to the Google App Engine application root folder (which includes app.yaml file).

Type: String Default value: null Required: no

Application name. Determines deployment target. If null, value specified in app.yaml will be used.

Type: String Default value: null Required: no

Application version name. Determines to which version the code will be deployed. E.g. when version: 'dev' code will be deployed to dev.your-app.appspot.com. If null, code will be deployed to default version, i.e. your-app.appspot.com.

Type: String Default value: 'oauth2' Required: yes, except for 'run' and 'kill' actions.

Enables OAuth2 if the value is 'oauth2', otherwise path to a gae.auth file with app developer / admin credentials. The file format is: name@domain.com password
IMPORTANT: please always add that file to .gitignore to ensure its confidentiality.
OAuth2 NOTE: you need to be logged in with your applications administrator account in your default browser for OAuth2 to work.

Type: Boolean Default value: false Required: no

Specifies whether the action should be executed synchronously or asynchronously. Running asynchronously can be handy if you want to quickly manage the server with run and kill, or if you want to perform another task after running the server without a dedicated parallelization plug-in like grunt-concurrent. Currently supported only for the run action.

Type: Boolean Default value: false Required: no

Specifies whether console output should be allowed from the local Google App Engine development server when it is launched asynchronously, which can be helpful under some circumstances. Has no effect unless using options.async = true with the run action.

Type: Object Default value: {}

Additional command line arguments passed to Google App Engine scripts when executing the task. A full list of arguments can be found:

  • for run action: https://developers.google.com/appengine/docs/python/tools/devserver#Python_Command-line_arguments
  • for other actions: https://developers.google.com/appengine/docs/python/tools/uploadinganapp#Python_Command-line_arguments

E.g. specifying:

options: {
  args: {
    host: '0.0.0.0'
  }
}

will result in appending --host=0.0.0.0 to the executed GAE command.

Type: Array Default value: []

Additional command line flags (value-less) passed to Google App Engine scripts when executing the task. A full list of flags can be found:

  • for run action: https://developers.google.com/appengine/docs/python/tools/devserver#Python_Command-line_arguments
  • for other actions: https://developers.google.com/appengine/docs/python/tools/uploadinganapp#Python_Command-line_arguments

E.g. specifying:

options: {
  flags: [
    'no_cookies'
  ]
}

will result in appending --no_cookies to the executed GAE command.

This example task starts local Google App Engine development server synchronously. It means that until the server's log messages will appear in console and until the server is stopped, no further Grunt tasks will execute.

grunt.initConfig({
  gae: {
    run_sync: {
      action: 'run'
    }
  }
});

This example task starts local Google App Engine development server asynchronously. It means that no server logs will be shown in the console and Grunt will immediately proceed to executing next tasks in the queue. It also means that it will not be possible to determine if the development server started successfully other than by trying to access it via its local address in the browser. If for some reason the server does not start, temporarly make the action synchronous for debugging.

grunt.initConfig({
  gae: {
    run_async: {
      action: 'run',
      options: {
        async: true
      }
    }
  }
});

By default local GAE dev server starts on port 8080. According to dev_appserver.py documentation it is possible to run the server on a differnt port by specifying a --port=... flag. As every other flag, this can be done by adding port to the args object in options:

grunt.initConfig({
  gae: {
    run_async_port9999: {
      action: 'run',
      options: {
        async: true,
        args: {
          port: 9999
        }
      }
    }
  }
});

If local GAE dev server has been started asynchronously, it can be stopped with the following task:

grunt.initConfig({
  gae: {
    stop: {
      action: 'kill'
    }
  }
});

Deploying to Google App Engine requires being logged in with the application's administrator account in the default web browser, or a valid gae.auth file for non-OAuth2 transactions (please see options section above).
The following task will deploy the code to default Google App Engine instance (i.e. your-app.appspot.com) using OAuth2:

grunt.initConfig({
  gae: {
    deploy_default: {
      action: 'update'
    }
  }
});

Deploying to Google App Engine requires being logged in with the application's administrator account in the default web browser, or a valid gae.auth file for non-OAuth2 transactions (please see options section above).
The following task will deploy the code to dev Google App Engine instance (i.e. dev.your-app.appspot.com) reading the authentication credentials from 'gae.auth' file:

grunt.initConfig({
  gae: {
    deploy_dev: {
      action: 'update',
      options: {
        auth: 'gae.auth',
        version: 'dev'
      }
    }
  }
});

Deploying to Google App Engine requires being logged in with the application's administrator account in the default web browser, or a valid gae.auth file for non-OAuth2 transactions (please see options section above).
The following task will deploy the code to Google App Engine application different than the one specified either in global options or in app.yaml:

grunt.initConfig({
  gae: {
    deploy_different_app: {
      action: 'update',
      options: {
        application: 'grunt-gae-another-app'
      }
    }
  }
});

Updating indexes requires being logged in with the application's administrator account in the default web browser, or a valid gae.auth file for non-OAuth2 transactions (please see options section above).
The following task will update indexes of grunt-gae-another-app application.

grunt.initConfig({
  gae: {
    update_indexes: {
      action: 'update_indexes',
      options: {
        application: 'grunt-gae-another-app'
      }
    }
  }
});

Rolling back transaction requires being logged in with the application's administrator account in the default web browser, or a valid gae.auth file for non-OAuth2 transactions (please see options section above).
The following task will rollback the current transaction.

grunt.initConfig({
  gae: {
    update_indexes: {
      action: 'rollback',
    }
  }
});

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Please report all issues directly on the Github Issues page.
Whenever reporting an issue, please run the task in which you can observe a bug with a --debug flag, e.g. grunt gae:your_buggy_task --debug and include full output from your console.

  • 2013-10-06 v0.2.0 Flags added, OAuth2 support added.
  • 2013-08-17 v0.1.0 Initial release.