Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    grunt-gaepublic

    grunt-gae

    Build Status

    Google App Engine management plugin for Grunt.

    About

    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.

    Getting Started

    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.

    The "gae" task

    Overview

    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.
          }
        },
      },
    })

    Actions

    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.

    run

    Special action. Runs local Google App Engine development server.

    kill

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

    update

    Deploys the app to Google App Engine.

    update_indexes

    Updates indexes.

    vacuum_indexes

    Deletes unused indexes.

    update_queues

    Updates Task Queue configuration

    update_dos

    Updates the DoS protection configuration

    update_cron

    Manages scheduled tasks specified in cron.yaml

    Options

    options.path

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

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

    options.application

    Type: String Default value: null Required: no

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

    options.version

    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.

    options.auth

    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.

    options.async

    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.

    options.asyncOutput

    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.

    options.args

    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:

    E.g. specifying:

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

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

    options.flags

    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:

    E.g. specifying:

    options: {
      flags: [
        'no_cookies'
      ]
    }
    

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

    Usage Examples

    Running local Google App Engine development server synchronously.

    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'
        }
      }
    });

    Running local Google App Engine development server asynchronously.

    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
          }
        }
      }
    });

    Running local Google App Engine development server on a non-standard port.

    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
            }
          }
        }
      }
    });

    Stopping local Google App Engine development server that was started asynchronously.

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

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

    Deploying the code to a default version

    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 the code to a specific non-default version

    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 the code to a different application

    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

    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.

    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',
        }
      }
    });

    Contributing

    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.

    Reporting issues

    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.

    Release History

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

    githalytics.com alpha githalytics.com alpha

    install

    npm i grunt-gae

    Downloadsweekly downloads

    9

    version

    0.2.4

    license

    none

    repository

    githubgithub

    last publish

    collaborators

    • avatar