Skip to content

Command line interface

Jump to bottom
Michael Keller edited this page Jul 2, 2015 · 11 revisions

Installing the Kestrel CLI

The second part of Kestrel is how you actually interface with it.

1. Install NodeJS

To install, you need NodeJS, which you can either install with homebrew with

brew install node

Or with the package installer from http://nodejs.org/.

2. Install Kestrel-cli

Install the package with the -g flag, meaning that you want the command-line version:

npm install -g kestrel-cli

To update, run:

npm update -g kestrel-cli

3. Configure

All commands are available by typing swoop [command] and works on a system of prompts. But more on that later. For now, just run swoop config and you'll be asked to fill out all the necessary configuration parameters. Which are...

Name Default Options Type Description
GitHub account type "" "org" or "individual" string Is your GitHub account that you'll be pushing to an organization or an individual account?
Account name "" anything string The name of that account
Login method "https" "https" or "ssh" string How do you connect to GitHub? Through https or through an ssh key?
Private repos by default false true or false boolean When you create a repo with swoop init should it be private
Server url "" string The URL of your Kestrel Server. Something like "http://54.112.32.32:9001"
Sync deploy trigger "" anything string The keyword that will trigger a deployment to S3. This will "sync" your files, only modifying changed files
Enable hard deploy false true or false boolean Enable a deploy trigger that will overwrite existing S3 files and delete S3 files that don't exist in your repo.
Hard deploy trigger "" anything string The keyword that will trigger a hard deploy, if enabled.
Default S3 path '2014' anything string The folder on S3 where you put your repos be default
Archive repo name "archive" anything string If you want to archive your projects as branches in another GitHub repo, put the name of that repo here.

Running swoop config and saving these options will store a file called kestrel-config.json in ~/.conf/. If the ~/.conf/ folder doesn't exist already, it will be created.

3. Usage

All commands are available by typing swoop [command]. They are:

  • config - Set up configuration.
  • init - Init a new Kestrel project.
  • deploy - Publish to S3.
  • archive - Push a branch of this repo to a new branch on the archive repo.
  • unschedule - Clear all previously scheduled deploys on an environment-specific basis.

Initing

When you start a project, you'll want to run swoop init, which will do three things:

  • Runs git init
  • Creates a .kestrel folder in your local repo.
  • Creates a remote GitHub repo an sets the remote.
  • Adds a webhook on this newly created repo to the Kestrel Server. The webhook is the link that watches the repo for changes and pulls them down to the Kestrel Server.

Deploying

You'll be prompted for the following info:

  • bucket_environment — staging or prod environment as set in the config.
  • trigger_type — sync or hard deploy method. sync will do what it sounds life it does but it won't remove any files. hard will sync and remove remote files that don't exist locally.
  • local_path — What folder do you want to push. This can be a subdirectory such as project/audio.
  • remote_path — Where do you want to put it on S3?
  • when — The time to schedule a deploy in YYYY-MM-DD HH:MM format, 24-hour clock.

Scheduling

Each environment, production and staging, has its own scheduling queue. You can schedule a deployment for a time in the future. All times are in the timezone you define in the config. Only one deployment per environment can be schedule at a time. Any double scheduling will overwrite the first. For instance, you deploy to staging with a timestamp of 2015-04-01 14:00 and then, also to staging, with 2015-04-01 14:30. The second scheduling will overwrite the first.

If you were to schedule the second deploy to the production server, both deployments will run.

Another scenario is that you schedule a deploy for tomorrow morning but there are some changes that come through so you commit and push them to GitHub. As long as you push those changes, they will be included in the already scheduled deploy without having to issue another deploy command.

Unscheduling

You can clear an environment's queue by running swoop unschedule. You'll be prompted for the environment and the sync trigger. The sync trigger is required a security measure — if you need a password to deploy, you need one to cancel deployments.

Archive

One way to archive repos is to add them as a branch on a predesignated archive repo, which you can set in your config. Run swoop archive and you'll be asked which branch in your current repo you want to archive and what name you want to give it on the archive repo. For example, master and 2014_projectname will take the current master branch and give it a proper name on the archive repo.

By default, it will look to your .kestrel/deploy-settings.json to try and discern from your remote path what year and month this was published in. For instance, if you deploy to 2014/01/projectname then your archive branch will be called 2014_01_projectname. If you don't have a month, it will be 2014_projectname. As you can see, it will replace the / with _s.

If you are archiving a branch other than master, it will append that branch name to the string preceded by two underscores. For example, 2014_01_projectname__testbranch.

You can also set this with flags such as swoop archive -b master:2014_projectname

Clone this wiki locally