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.

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

List running EC2 instances ec2-list-json

Returns a JSON list of running EC2 instances. Defaults to filtering by running state. You can use ec2-list-json:all to remove the filter, or pick another instance-state-name to filter by.

Describe an instance with ec2-lookup

Similar to ec2-list-json, but lets you get the properties of an instance by name, rather than state. Try it with grunt ec2-lookup:staging.

Get an SSH connection command for an instance ec2-ssh-text:name

Gives you a command you can copy and paste to connect to an EC2 instance through SSH. Useful to get down and dirty.

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

Feedback

Enjoy it. Submit any issues you encounter, and send any feedback you might have my way.