README.md

Rocketry Documentation

Table of Contents

• Quick Start
  • Installation
  • Configuration
  • Authentication
    • Via Username & Password
    • Via SSH key pairs
  • Test a Manual Deployment
• Documentation
  • Commands
  • Configuration Keys
• Guides
  • Setup with DigitalOcean
  • Setup with Linode
  • Integration with Github Actions
  • Integration with Travis CI

🏃🏼‍ Quick Start

Installation

To get started, add rocketry as a dev dependency:

# With npm
npm install -D rocketry

# or

# With yarn
yarn add -D rocketry

Configuration

To configure rocketry create a .rocketryrc file at the root of your project with the following required keys filled out:

// .rocketryrc

{
	// Your target server's IP address here.
	host: '0.0.0.0',
	// Define an array of files and/or folders that you want to upload to the
	// server. Do not add `node_modules` here. They will be configured
	// automatically for you.
	sources: [
		'some_directory',
		'package.json',
		'start.js'
	],
	// Specify where on the target server you want your files to be placed.
	// Somewhere in /var/www/ is a good place if you can't decide.
	target_dir: '/var/www/example',
	// Specify what user should be used to connect to the server via SSH.
	user: 'root'
}

Authentication

Authentication with your server is the only tricky part of working with rocketry. There are two ways to handle authentication: via username & password, or via an SSH key pair.

Via Username & Password

NOTE: When using username/password authentication, your password is assumed to be base64 encoded. This is done deliberately for security reasons.

To authenticate a deployment via a username and password, ensure the user configuration key is set in your .rocketryrc file, and pass the password to your rocketry run command via the ROCKETRY_PW environment variable, like this:

ROCKETRY_PW=yourBase64EncodedPasswordHere npx rocketry run

Via SSH key pairs

To authenticate a deployment via an SSH key, specify the private_key_path configuration key in your .rocketryrc file. You'll be prompted to enter your private key passphrase when you run:

npx rocketry run

Test a Manual Deployment

Now that you've got rocketry configured, all you need to do is run:

# With npm
npx rocketry run

# or

# With yarn
yarn rocketry run

You can add the --debug flag to the end of that command to see detailed output of exactly what rocketry is doing.

📝 Documentation

Commands

The following rocketry commands are supported:

• rocketry run: Perform a production deployment
• rocketry version: Prints the current version of rocketry

Configuration Keys

Configuration is done via cosmiconfig which allows rocketry to be configured via:

• a package.json rocketry property, or
• a .rocketryrc file, or
• a .rocketryrc.js file, or
• a rocketry.config.js file

The following configuration keys are supported:

Required Keys

Key	Type	Default Value	Description
host	string		The IP address of the server you will be deploying to.
sources	Array<string>		An array of file and folder paths (using glob syntax) that you want uploaded to your server.
target_dir	string		The path to the target directory on the server where you want your application deployed.
user	string	root	The name of the SSH user to use to authenticate with the server.

Optional Keys

Key	Type	Default Value	Description
name	string	Your package.json:name value	The name of your application (used in the pm2 configuration). By default, the "name" value from your "package.json" will be used.
private_key_path	string	~/.ssh/id_rsa	The path to your local private SSH key file which will be used to authenticate with the server.