DeployerJS

Yet Another Deployement Tool : soon™

Why Another Deployement Tool ?

Pure javascript, no binary needed on the local machine, forget about under-the-hood shellscript or rsync/ssh binary spawn. I just want to run this tool everywhere (even under windows, yes, windows) i can run NodeJS.

How to use it ?

CLI Overview

deployer update        <environement|group> [file]       # update remote to latest
deployer rollback      <environement|group> [file] [n]   # revert to [n]th last
deployer currrent      <environement|group> [file]       # output current release commit
deployer previous      <environement|group> [file]       # output previous release commit
deployer execute <cmd> <environement|group> [file]       # execute the given <cmd>
deployer list          <environement|group> [file]       # list previous deployements

CLI options

You can specify some options when using the CLI :

• -d or --details when set to true, a file containing detailed logs of the deployement will be created in the current directory
• -s [strategy] or --strategy [strategy] choose the strategy used to deploy, see below for explanation
• -r [reporter] or --reporter [reporter] choose the reporter used to show deployement info, see below for explanation

Configuration

DeployerJS is based on the configuration architecture of PM2, so we represent a remote environnement like this (where production is the environnement name) :

{
  "production": {
      "user": "totallynotroot",                             // ssh user
      "host": "127.0.0.1:22"                                // host adress + ssh port
      "ref": "origin/master",                               // remote branch
      "repo": "[email protected]:vmarchaud/deployerjs.git",    // git repo
      "path": "/home/totallynotroot/myprod/",               // path where the deployement will be done 
      "passphrase" : true,                                  //  if my rsa key have a passphrase
      "post-deploy": "npm install",                         // will be executed after update on remote system
      "post-deploy-local": "touch deploy.done",             // will be executed after update on local system
      "env" : {                                             // all remote hooks will be executed with this env
        "NODE_ENV": "production"
      }
  }
 }

To list all environnements you have two choices, put the list at the root of the JSON document (like above) or specify deploy object that will list them (example here with a package.json file) :

  {
  "name": "myproject",
  "version": "0.0.1",
  "scripts": {
    ...
  },
  "dependencies": {
    ...
  },
  "deploy" : {              // here you can define the environnement entries
    "staging" : { ... },    // define here your staging environnement
    "production" : { ... }  // define here you production environnement
  }
}

Here are the principal options you can set in a environnement :

| Option key | Value Type | Default | Example | Description | | ---------: | -----------:| -------:| --------:| -----------:| | user | String | | root | username used to authenticate to the ssh server | | host | String or Array | | ['localhost:22'] or localhost | can contains port of the remote host, array may contains multiple hosts | | port | String or Number | 22 | 22 or "22" | port of the remote ssh server | | password | Boolean | false | true or false | set a password to connect | | privateKey | String | ~/.ssh/id_rsa | a valid path on local system | use a rsa key to connect | | passphrase | Boolean | false | true or false | set a passphrase to use the rsa key | | path | String ||| remote path where the deployement will be done | | group | String | | production | set the group of the environnement (usefull to deploy on a group of servers) | | path | String ||| remote path where the deployement will be done | | env | Object || { "NODE_ENV": "production" }| environnement used to execute remote hooks | | ssh_options | Object | | { "agent": "myagent_path" } | options for ssh see ssh2 connect doc |

Hooks

You can tell deployerjs to execute commands for you, we call them hooks, they can be run either on remote or local system, you just need an entry in the configuration (like the above example), here are the current hooks :

• pre-setup & pre-setup-local
• post-setup & post-setup-local
• post-rollback & post-rollback-local
• post-deploy & post-deploy-local

Deployement Strategy

Deployement action (like updating/rollbacking) are done via Strategy, the default is theGitStrategy that will simply use git on the remote server to execute all commands necessary to deploy the code, they use their own key/value configuration, so i split their configuration.

Available strategies (and the corresponding CLI option to use) :

• GitStrategy (--strategy git)

GitStrategy

Configuration

| Option key | Value Type | Default | Example | Description | | ---------: | -----------:| -------:| --------:| -----------:| | ref | String | origin/master| any origin and branch separed by slash | Which remote and branch should be used | | branch | String | master | | branch used (override ref) | | origin | String | origin | | origin used (override ref) | | repo | String | | github.com/vmarchaud/deployer | Git repo URI |

Deployment Reporter

To display information relative to deployement, we use a reporter (just a class with some methods) that will handle display of information.

By default the StdReporter is used, it will just print all data to STDOUT.

Available reporters (and the corresponding CLI option to use) :

• StdReporter (--reporter std)
• SpinnerReporter (--reporter spinner)

Architecture

Because you want to know how to fork this and start hacking it :

soon™

Relevant documentation

• ssh2 - the module used to connect over a SSH connection to the servers
• ssh2-streams - the module used by ssh2 to implement some protocols (sftp mainly used here).

TODO:

• More reporters
• More strategies
• Things to remember to fix :
  • [ ] git clone without host verified