Installation

npm install --save-dev grunt-ec2

For every task in this document, 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.

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 through the CLI 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_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_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.

"AWS_RSYNC_USER"

The user to SSH into the instance when deploying through rsync.

"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.

"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_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_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_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.

"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.

"NODE_SCRIPT"

The path to your script. Defaults to app.js, as in node app.js. Relative to your cwd.

"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_ROOT"

The relative path to your static folder root, for example: bin/public. Used to serve static assets through nginx.