paratrooper

Deployment CLI for Node on Ubuntu (nginx & upstart) with Git

paratrooper

They are used for tactical advantage as they can be inserted into the battlefield from the air, thereby allowing them to be positioned in areas not accessible by land. -- Wikipedia

A CLI tool for deploying a node web app to an Ubuntu server with nginx, upstart and git, in a simple way. Tested with Github and Bitbucket repositories.

npm install -g paratrooper

The remote machine must have git, nginx, node and npm installed before deployments can be made to it. The machine should also be configured for remote access via ssh. See the wiki for more information.

pt <init|deploy|remove> [target] -d <directory>

note: You can also use paratrooper instead of pt for verbosity.

  • Run pt init [target] to generate the deploy config files. You need to commit and push these files before deploying.
  • Run pt deploy [target] to begin a deployment.
  • Run pt remove [target] to stop and remove the app from the server.

If you omit the [target] for deploy or remove commands, then you'll either get a list of available targets, or it will automatically select the target, if you only have one.

First run pt init and answer the questions. It will try to guess some settings for you – if you're happy with the guess, just hit enter to accept it:

pt init

Commit your repo with the new deplyoment directory and it's contents, then deploy.

pt deploy

Paratrooper uses the project's package.json file to present you with some sane defaults, so it's recommended to have the name and repository fields filled out before executing pt init [target].

Specifies the type of environment, and is an arbitrary value based on your workflow. Target is usually alpha, beta, staging, or production, but you are free to specify whatever value you want. Each target has it's own set of configurations. If a target isn't specified, then by default it's production.

Config files are stored in the deploy directory unless you specify a custom directory via -d <directory>. Example: pt deploy -d deployconfigs. If this option is used with pt init, it must be used with all other commands.

Used for repos where the application root directory isn't at the root of the repository, so something like webapp/ might be valid input for your project. This value defaults to the root of the repository.

Pass through the ssh -i option for working with certain servers where you don't have a password, but a key file instead. This option is available for deploy and remove commands.

After running pt init, you'll be asked a series of questions. Here's what each answer is used for:

This is the public URL your app will be served from on the server you are deploying to.

The URL of the repo. The repo is cloned on the first deploy and then pulled from thereafter.

This is the git branch that you want your application source to be cloned/pulled from.

This is usually production or maybe development, and dictates how your app is built or served.

The port the node app listens on. This is needed to properly link the node process with the upstream nginx server.

The SSH address for your deployment server, so we can setup/deploy your app. The user + host address of the server, i.e. root@yourserver.com or myname@123.23.211.23 or deployuser@someinstance.

This is a Yes/No question and will show the next question if answered 'Y' (the default answer).

Select available npm scripts that are in your package.json's scripts object. The postinstall and install scripts are filtered out of this list. This question is only asked if the answer to the above question is 'Y'.

  • Following a successful deploy, pt will wait a further 15 seconds (to account for the configured respawn limits of upstart) to verify the app process is still alive and well.

  • As a shorthand, the pt init, pt deploy, pt remove commands can also be referred to by their first letter, i.e. pt i, pt d and pt r respectively.

  • If no errors are reported, the command was successful. The appropriate zero or non-zero error code is returned to allow pt to be invoked by third party tools.

  • It's assumed that all files in the sites-enabled nginx directory are valid config files, i.e. that your nginx.conf includes them using something like this include /etc/nginx/sites-enabled/*;.

Tests are written using prova (tape), and can be executed via npm test.

This project is based off Martin Rue's node-deploy.