README
dropper
Deploy things!
Installing
$ npm install -g dropper
Platforms
Dropper is built to be extensible. The first platform supported is OpsWorks, but maybe there are more to come!
Opsworks
Deploy an OpsWorks app:
$ dropper opsworks --stack-id STRING --app-id STRING
Options
--access-key-id STRING
(required) AWS access key. Can be provided by theAWS_ACCESS_KEY_ID
environment variable.--secret-access-key STRING
(required) AWS secret key. Can be provided by theAWS_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 isus-east-1
. Can be provided by theAWS_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:
{
"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:
// 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'));
Registering
Deployers need to be registered on the main Deployer
class:
// 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.
Events
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.
CloudinatorDeployer.prototype.deploy = function() {
if (this.cloudinate()) {
this.emit('done');
} else {
this.emit('error', 'Cloudination failed!');
}
}
Command Line Arguments
Deployers are instantiated with an object containing command line arguments.
Option names are converted from --lower-case-with-dashes
to camelCase
.
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;
}
Deploying
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.
CloudinatorDeployer.prototype.deploy = function() {
// Deploy things!
this.emit('done');
}
Tests
To run the tests:
$ npm install
$ npm test
Contributing
- Fork the GitHub repo.
- Check out a feature branch, e.g.
cool-new-thing
. - Write tests! Pull requests won't be accepted without reasonable test coverage.
- Write code!
- Open a pull request on GitHub.
License
MIT. See LICENSE.