grunt-ec2

Grunt tasks to create, terminate, and deploy to AWS EC2 instances

grunt-ec2

Grunt tasks to create, terminate, and deploy Node applications to AWS EC2 instances, then proxy with nginx

Abstracts away aws-sdk allowing you to easily launch, terminate, and deploy to AWS EC2 instances.

Note: This is a very, very opinionated package. You're invited to fork it and produce your own flow, and definitely encouraged to create pull requests with your awesome improvements.

Jump to the task reference to see what it can do.

Features

This is pretty feature packed

Launch EC2 instances and set them up with a single task. Look ma', no hands!
Shut them down from the console. No need to look up an id or anything.
Use individual SSH key-pairs for each different instance, for increased security
Deploy with a single Grunt task, using rsync for speed
Use pm2 to deploy and do hot code swaps!
Works after reboots, too
Introduced at Pony Foo
Put an nginx proxy server in front of Node
Get tons of Grunt tasks to manipulate your EC2 instances
Supports turning on ssl and spdy in your nginx server!

Installation

npm install --save-dev grunt-ec2

You'll need to set up the AWS configuration for the project. You'll also need to have a Security Group set up on AWS. Make sure to enable rules for inbound SSH (port 22) and HTTP (port 80) traffic.

Setup

grunt.initConfig({
    pkg: grunt.file.readJSON('package.json'),
    ec2: 'path/to/whatever.json'
});
 
grunt.loadNpmTasks('grunt-ec2');

Then, in your whatever.json file:

{
  "AWS_ACCESS_KEY_ID": "<redacted>",
  "AWS_SECRET_ACCESS_KEY": "<redacted>",
  "AWS_SECURITY_GROUP": "something"
}

You'll need to get an access key pair for AWS, as well as create a security group on AWS by hand. Creating security groups is not supported by this package yet.

The package.json entry is used to take the version number when deploying.

For the ec2 configuration, I don't take an object directly to encourage hiding away the deployment variables, granting them only to people who can actually perform deploys. You could provide an object directly, but it's strongly discouraged.

Configuration

If you're confident enough, you can use the tool with just those options. Here is the full set of options and their defaults.

Variable Name	Purpose
`"AWS_DEFAULT_REGION"`	Passed to the CLI directly, defaults to `"us-east-1"`
`"AWS_ELB_NAME"`	The default Elastic Load Balancer you want to use with `ec2-elb-attach` and `ec2-elb-detach`.
`"AWS_IMAGE_ID"`	Used when creating a new instance with the `ec2-create-instance` task. Defaults to the `"ami-c30360aa"` Ubuntu AMI.
`"AWS_INSTANCE_TYPE"`	The magnitude for our instance. Defaults to `"t1.micro"`. Used when creating instances.
`"AWS_RSYNC_USER"`	The user to SSH into the instance when deploying through `rsync`.
`"AWS_SECURITY_GROUP"`	The security group used for new instances. You'll have to create this one yourself.
`"AWS_SSH_USER"`	The user used to SSH into the instance when setting it up for the first time, after creating it.
`"ELASTIC_IP"`	Assign an AWS Elastic IP to new instances, and release it when terminating them. Defaults to `true`.
`"ENV"`	Provided as a JSON object. Variables to set in the local environment before the app starts. Useful for setting up DB credentials for example.
`"NGINX_ENABLED"`	Whether to install and use `nginx`. If installed, the Node application must listen on port `NGINX_PROXY_PORT`. Keep in mind that since we're going to use `pm2` to spin up a cluster, a single port won't be an issue anyways.
`"NGINX_PROXY_PORT"`	This is the port where `nginx` will proxy requests to, when it won't handle them by itself. This is the same port you'll want to use to listen with your Node application.
`"NGINX_SERVER_NAME"`	The server name for your static server, for example: `bevacqua.io`.
`"NGINX_STATIC_ERRORS"`	The relative path to your error HTML views folder root. For example `bin/views/error`.
`"NGINX_STATIC_ROOT"`	The relative path to your static folder root, for example: `bin/public`. Used to serve static assets through `nginx`.
`"NGINX_USER"`	The user to configure and run `nginx` with.
`"NGINX_WORKERS"`	The amount of workers processes used by `nginx`.
`"NODE_SCRIPT"`	The path to your script. Defaults to `app.js`, as in `node app.js`. Relative to your `cwd`.
`"NPM_INSTALL_DISABLED"`	If `true`, won't `npm install --production` after deployments
`"NPM_REBUILD"`	If `true`, will `npm rebuild` after deployments
`"PAGESPEED_API_KEY"`	If provided, will run Google PageSpeed insights on every deployment. Get an API Key here. Requires you to setup `grunt-pagespeed` locally, in your own `Gruntfile.js`.
`"PROJECT_ID"`	Just an identifier for your project, in case you're hosting multiple ones, for some stupid reason, in the same instance. Defaults to `ec2`. This is used when creating folders inside the instance.
`"RSYNC_EXCLUDE_FROM"`	Relative path to an rsync exclusion patterns file. These are used to exclude files from being uploaded to the server during `rsync` on deploys. Defaults to ignoring `.git` and `node_modules`.
`"RSYNC_EXCLUDES"`	An array of file patterns to explicitly exclude during deploys. The `%NODE_ENV%` string will be replaced by the name tag. Unset by default.
`"RSYNC_INCLUDE_FROM"`	Relative path to an rsync inclusion patterns file. These are used to include files for upload to the server during `rsync` on deploys. Unset by default.
`"RSYNC_INCLUDES"`	An array of file patterns to explicitly include during deploys. The `%NODE_ENV%` string will be replaced by the name tag. Useful for uploading environment configuration.
`"SSH_KEYS_FOLDER"`	The relative path to a folder where you want to use with tasks that create SSH key-pairs. It doesn't need to exist, `mkdir -p` will take care of that. This defaults to a folder inside this package, which is pretty lame if you want to look at the key-pairs yourself. Although you shouldn't need to, I've got you covered.
`"SSL_CERTIFICATE"`	Relative path to your unified SSL certificate.
`"SSL_CERTIFICATE_KEY"`	Relative path to your private certificate key.
`"SSL_ENABLED"`	Enables SSL configuration on `nginx`. Learn how to set it up for free.
`"SSL_STRICT"`	Whether to send a `Strict-Transport-Security` header.
`"VERBOSITY_NPM"`	Determines the output verbosity for `npm` during deployments, values are limited to `loglevel` option values for `npm`. Defaults to `info`, just like `npm` does.
`"VERBOSITY_RSYNC"`	Determines the output verbosity for `rsync`. Possible values limited to `'v'`, `'vv'`, and `'vvv'`. Defaults to `''` (not verbose at all, my friend).
`"PM2_INSTANCES_COUNT"`	Set number processes to start with pm2. default is 2 and valid values are integers or 'max' for setting the maximum processes depending on avaible CPUs

Tasks

Although this package exposes quite a few different tasks, here are the ones you'll want to be using directly.

Launch an EC2 instance `ec2-launch:name`

Launches an instance and sets it up.

Creates an SSH key-pair
Uploads the public key to AWS
Creates an AWS EC2 instance
Tags the instance with the friendly name you provided
Pings the instance until it warms up a DNS and provides SSH access (typically takes a minute)
Sets up the instance, installing Node, npm, and pm2

Example:

grunt ec2-launch:teddy

Shutdown an EC2 instance `ec2-shutdown:name`

Terminates an instance and deletes related objects

Looks up the id of an instance tagged name
Terminates the AWS EC2 instance
Deletes the key-pair associated with the instance

Example:

grunt ec2-shutdown:teddy

grunt ec2-ssh-text:teddy

Deploy to an EC2 instance `ec2-deploy`

Deploys to a running EC2 instance using rsync over SSH.

Connects to the instance through SSH
Uploads cwd to an rsync folder such as /srv/rsync/example/latest
Only transmits changes, similar to how git operates
Using pkg.version, creates a folder with the newest version, like /srv/apps/example/v/0.6.5
Creates a link from /srv/apps/example/v/0.6.5 to /srv/apps/example/current
Either starts the application, or reloads it with zero downtime, using pm2
Instance name can be accessed through process.env.NODE_ENV

Example:

grunt ec2-deploy:teddy

Deploy to multiple EC2 instances `ec2-deploy-many`

Queries EC2 for instances that match the given name and deploys to each on using ec2-deploy.

Example:

grunt ec2-deploy-many:teddy*

Reboot an instance with `ec2-reboot`

Reboots the instance by the specified name.

Looks up instance id for instance tagged name.
Reboots it

Example:

grunt ec2-reboot:teddy

Complete Task Reference

Task and Target(s)	Purpose
`ec2-assign-address:id`	Allocates an IP and assigns it to your instance
`ec2-assign-existing-address:id:ip`	Assigns an IP address to an instance without allocating a new one
`ec2-create-keypair:name`	Generates an RSA key pair and uploads the public key to AWS
`ec2-create-tag:id:name`	Tags an instance with the provided name
`ec2-delete-keypair:name`	Removes the remote and the local copies of the RSA key
`ec2-delete-tag:id`	Deletes the associated name tag for an instance
`ec2-rename-tag:old:replacement`	Tags an instance using a different name
`ec2-deploy:name`	Deploys to the instance using `rsync`, reloads `pm2` and `nginx`
`ec2-deploy-many:name`	Gets instances filtered by name tag and deploys to the instance using `rsync`, reloads `pm2` and `nginx`
`ec2-elb-attach:instance-name:elb-name?`	Attaches an instance to an ELB
`ec2-elb-detach:instance-name:elb-name?`	Detaches an instance from an ELB
`ec2-launch:name`	Creates a new instance, giving it a key-pair, a name tag, and an IP. Then sets it up
`ec2-list:state`	Lists instances filtered by state. Defaults to `running` filter, use `all` to disable filter.
`ec2-list-json:state`	Lists instances filtered by state. Defaults to `running` filter, use `all` to disable filter. Prints results in JSON
`ec2-logs-nginx-access:name`	Gets `nginx` access logs
`ec2-logs-nginx-error:name`	Gets `nginx` error logs
`ec2-logs-node:name`	Gets `pm2` logs
`ec2-lookup:name`	Gets instance filtered by name tag
`ec2-lookup-json:name`	Gets instance filtered by name tag. Prints results in JSON
`ec2-nginx-configure:name`	Installs `nginx` if necessary, updates its configuration files
`ec2-nginx-reload:name`	Reloads `nginx`
`ec2-nginx-restart:name`	Restarts `nginx`
`ec2-nginx-start:name`	Starts `nginx`
`ec2-nginx-stop:name`	Stops `nginx`
`ec2-node-list:name`	Returns output for `pm2 list`
`ec2-node-monit:name`	Runs `pm2 monit`
`ec2-node-reload:name`	Reloads app using `pm2 reload all`
`ec2-node-restart:name`	Restarts app using `pm2 restart all`
`ec2-node-start:name`	Starts app using parameterized `pm2 start`
`ec2-node-stop:name`	Stops app using `pm2 stop all`
`ec2-pagespeed:ip`	Requests the Google PageSpeed API, prints insights
`ec2-pm2-update:name`	Updates `pm2` on an instance, using `npm update -g pm2`
`ec2-reboot:name`	Reboots the EC2 instance
`ec2-release-address:ip`	Releases an IP address
`ec2-run-instance:name`	Spins up an EC2 instance, gives a name tag and assigns an IP
`ec2-setup:name`	Sets up port forwarding, installs `rsync`, `node`, and `pm2`, enqueues `ec2-nginx-configure`
`ec2-shutdown:name`	Terminates an instance, deleting its associated key-pair, IP address, and name tag
`ec2-ssh:name`	Establishes an `ssh` connection to the instance, you can emit commands to your EC2 instance
`ec2-ssh-text:name`	Displays a verbose command with which you can establish an `ssh` connection to the instance
`ec2-terminate-instance:id`	Terminates an instance
`ec2-version:name`	Get the version number currently deployed to EC2
`ec2-wait:id`	Waits for an instance to report a public DNS and be accessible through `ssh`