dropper

Deploy things!


Installing

``bash
$ npm install -g dropper
`

Platforms

Dropper is built to be extensible. The first platform supported is OpsWorks,
but maybe there are more to come!

$3

Deploy an OpsWorks app:

`bash
$ dropper opsworks --stack-id STRING --app-id STRING
`

#### Options

- --access-key-id STRING (required) AWS access key. Can be provided by the
AWS_ACCESS_KEY_ID environment variable.
- --secret-access-key STRING (required) AWS secret key. Can be provided by
the AWS_SECRET_ACCESS_KEY environment variable.
- --stack-id STRING (required) OpsWorks stack ID.
- --app-id STRING (required) OpsWorks app ID.
- --region STRING (required) AWS region. Default is us-east-1. Can be
provided by the AWS_DEFAULT_REGION environment variable.
- --revision STRING (optional) A revision, e.g. a git ref or subversion
revision number, to deploy.
- --migrate (optional) Enable migrations.
- --comment STRING (optional) Comment for the deployment.
- --wait-for-deploy (optional) Waits for deployments to complete before
exiting, and reports the result.

#### Permissions

It's recommended to create an IAM user with
just enough permissions to perform the actions required to deploy an app.
following permissions should be enough:

`json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"opsworks:CreateDeployment",
"opsworks:DescribeApps",
"opsworks:DescribeDeployments"
],
"Resource": [
"arn:aws:opsworks:::stack/your-opsworks-stack-id-here/"
]
}
]
}
`

Extending

Platform support is implemented through a Deployer. Each deployer lives in
its own module inside lib/deployer/.

Here's a working example:

`javascript
// In lib/deployer/cloudinator.js
function CloudinatorDeployer(options) {
this.options = options;
}

CloudinatorDeployer.prototype.cloudinate = function() {
// The cloud is very unpredictable
return Math.random() > 0.4;
}

CloudinatorDeployer.prototype.deploy = function() {
console.log('Cloudinating...');

if (this.cloudinate()) {
this.emit('done');
} else {
this.emit('error', 'Cloudination failed!');
}
}

exports = module.exports = CloudinatorDeployer;

// In lib/deployer.js
Deployer.register('cloudinator', require('./deployer/cloudinator'));
`

$3

Deployers need to be registered on the main Deployer class:

`javascript
// In lib/deployer/cloudinator.js
function CloudinatorDeployer(options) {}

exports = module.exports = CloudinatorDeployer;

// In lib/deployer.js, all the way at the bottom
Deployer.register('cloudinator', require('./deployer/cloudinator'));
`

After registering, you can call dropper cloudinator to use your deployer.

$3

Deployers are event emitters, and dropper handles a few special events:

- done events signal that a deploy has successfully completed. Every
deployer must emit this event when it's done.
- error events signal a fatal error and cause dropper to exit immediately
with a failed status.

> Error events should not be emitted in the constructor,
> because they won't have a handler registered.

`javascript
CloudinatorDeployer.prototype.deploy = function() {
if (this.cloudinate()) {
this.emit('done');
} else {
this.emit('error', 'Cloudination failed!');
}
}
`

$3

Deployers are instantiated with an object containing command line arguments.
Option names are converted from --lower-case-with-dashes to camelCase.

`javascript
function CloudinatorDeployer(options) {
// --fail-loudly
if (options.failLoudly) {
this.emit('error', 'BOOM');
}

// --deploy-target production
if (options.deployTarget == 'production') {
console.warn('omg r u sure');
}

// Save the options for later
this.options = options;
}
`

$3

Each deployer must implement the deploy method, which is called without
arguments. The deploy method is the entry point to the deployer, and should
emit either a done or an error event.

`javascript
CloudinatorDeployer.prototype.deploy = function() {
// Deploy things!
this.emit('done');
}
`

Tests

To run the tests:

`bash
$ npm install
$ npm test
`

Contributing

1. Fork the GitHub repo.
2. Check out a feature branch, e.g. cool-new-thing`.
3. Write tests! Pull requests won't be accepted without reasonable test
coverage.
4. Write code!
5. Open a pull request on GitHub.

License

MIT. See LICENSE.