Deployment CLI for Node on Ubuntu (nginx & upstart) with Git
MIT License
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/iojs 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.
pt init [target]
to generate the deploy config files. You need to commit and push these files before deploying.pt deploy [target]
to begin a deployment.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.
Supports Node.js and io.js. Be default it's set to latest
, which will be the latest version of io.js.
If you specify anything below 1.0, it will install Node.js, otherwise io.js.
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. [email protected]
or [email protected]
or deployuser@someinstance
.
postinstall
runs?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'.
.paratrooperrc
Paratrooper also supports a .paratrooperrc
file in your project's top level directory.
By default this file looks like this:
{
"directory": "deploy",
"rootPath": "",
"user": "",
"sshIdentityFile": "",
"debug": false
}
Note: You might have noticed, but the properties in this file map to the arguments available in the CLI.
Options specified in this file will be the new defaults for the given project, unless you explicitly set the matching arguments when using the CLI commands. See the Liftoff repo for more details and available arguments.
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.