do-deploy

deployment framework over ssh

npm install do-deploy
3 downloads in the last month

do

do is a small wrapper framework for the node module ssh2 (https://github.com/mscdex/ssh2) that provides fabric and capistrano-like multihost management and a sane and simple way to organize environment configs and remote task.

The code is written in node for node projects. Perhaps someday it could support other languages (if you wanna help ;)

Getting started

The best way to get started may be to check out the do-example (https://github.com/mattrenaud/do-example) project that implements a basic version in the .do subdirectory

Installation

Currently the best way to install is either as a global install or package.json dependency using the git url. Ill try and get this into npm as soon as possible

package.json:

{
  "name": "test-app",
  "version": "0.1.0",
  "author": "my@email.us",
  "description": "testing",
  "dependencies": {
    "do-deploy":"git+ssh://git@github.com:mattrenaud/do.git#master",
  }
}
$ ./node_modules/.bin/do dev deploy

or global:

$ npm install -g git://github.com/mattrenaud/do

The Basics

Project Structure

Your working directory should contain a .do folder. it should contain two subdirectories called config and tasks

config directory

the config directory contains "environment configurations", which are javascript modules that export either an object or a function.

  • objects will be merged into the config object
  • functions will be executed and the callbacks should execute in the normal (err,result) format, where result is the object to be merged into the config object

You may provide a global.js config file in this directory that will be associated with all environment configs

The order of merge is:

  1. package.json
  2. global.js
  3. .js

Properties in later merges will override the previous ones

Special config properties
  • all ssh2 (https://github.com/mscdex/ssh2) supported properties can be set on in any config file and will be passed to the underling client. the only exception to that is host (see below)
  • hosts can be set in your config as an array or an async function with a callback arg where you can pass an array of hosts in the second arg (if there is an err, put it in the first arg)
  • print can be set as an async function with a callback arg. this gives you the chance to print out any configs for your environment. for example you may want to print out the hosts that you discovered as a sanity check on your environment. this is executed after all the configs are loaded

tasks directory

This directory contains tasks that are named based on the filename. For each task, you can have a .js file, .sh file, or both. The .js file provides you the opportunity to gather parameters for the .sh or you can just do all the work in that script if there is no .sh file. Your .js files will run in the context of the config object, therefore all of the props in package.json and the config directory will available using this

.sh files are essentially bash scripts (or whatever your default shell is on the server side). The framework will run the script, but will first prepend what you pass in your .js file as variables (with the prefix 'P_')

for example say you pass the following javascript object:

{
  THINGY: 'thingy!!!'
}

you can then get access to that string like this:

echo what is that $P_THINGY

do Command

The command line do accepts the config name as its first argument and zero to many tasks in order of execution.

For example, lets say you have a config called prod and two tasks: deploy and restart, ways you may execute do are:

do prod

or

do prod deploy

or

do prod deploy restart

Execution path

Currently do will serially iterate over all of the tasks. For each task, it will serially iterate over all servers and perform that task. In other works, each task executes on all servers one at a time before the next task runs. I hope to be able to provide a parallel option soon.

License

MIT license

npm loves you