@bugcrowd/briareus/README.md

Briareus assists with Feature Branch deploys to ECS

# Briareus

Briareus is a tool to facilitate "feature branch deployments" on ECS. Its name comes from a creature from Greek mythology with 100 arms and 50 heads.

**NOTE:** We have moved the package under our `bugcrowd` NPM organization - this will be the only package location maintained going forward.

## Concepts
### Variants
Variants are unique variations of the application. Typically a git branch. Each variation gets a unique domain. It will persist until deleted.

### Deployments
Deployments are specific builds of the application. There can be many deployments in a variant.

## Purpose
Briareus improves the developer workflow for testing specific builds of an application while in development. Enabling fellow developers, stakeholders, QA and others to inspect the work during review.

## Features
- A unique domain and wildcard SSL Certificate per variant. Supports subdomains.
- The configuration is stored in git so that developers can change settings for their branch

## CLI Tool
### Installation
When used in CLI mode you can install briareus globally to get access to the `briareus ...` command. eg `npm install -g @bugcrowd/briareus`. Or skip the install by using `npx`. eg `npx @bugcrowd/briareus ...`.

### Usage
CLI documentation is available via the `briareus --help` command. `--help` is also available on subcommands.

```
briareus [command]

Commands:
  briareus cleanup  Cleanup old variants
  briareus deploy   Deploy a project with Briareus
  briareus destroy  Destroy a variant
  briareus get      Get a variant
  briareus init     Initialize a project to be deployable with Briareus
  briareus list     List variants
  briareus secrets  Manage secrets
  briareus start    Start the Briareus Service

Options:
  --version          Show version number                               [boolean]
  --projectRootPath  Path to the root of the project with a Briareus
                     configuration[default: "/Users/coenhyde/projects/briareus"]
  --endpoint         Endpoint of the briareus service
  --log-level        Endpoint of the briareus service          [default: "warn"]
  --help             Show help                                         [boolean]
```

### Project to deploy
Run `briareus init` in the project you want to deploy with Briareus. This will create a `.briareus` directory in the project root. Inside you will find two files `config.json` and `task-definition.json`.

### Managing secrets
A feature branch can communicate with existing services in Redama using environment variables and secrets stored in the `reponame/.briareus/config.json` file. A secret can be added using `npx @bugcrowd/briareus secrets set --authtoken secretauthtoken --scope scopename KEY=keyvalue` from the repo's root, where

- secretauthtoken can be found in 1Pass' 'Developer Share' vault under the name Briareus API Token,
- scopename is the named scope that the secret will be placed under in `config.json`, e.g. sidekiq, crowdcontrol...
- KEY is the name of the secret you wish to go into the config file
- keyvalue is the secret you wish to encrypt and add to the config. You can find an internal API token for another Bugcrowd service from the AWS Console's Systems Manager > Parameter Store, which lists both the KEY name mentioned above, and the keyvalue secret.

This command uses AWS' KMS (Key Management Service) to encrypt the key and update `.briareus/config.json`.

## Client Library
You can use the Briareus client library in other node applications.

### Installation
`npm install @bugcrowd/briareus --save`

### Usage
#### Initialization
```js
const BriareusClient = require('briareus/lib/client');

const options = { .. };
const briareus = new BriareusClient(options);
```

#### BriareusClient Options
- `endpoint` URL location of the Briareus Server
- `authtoken` Token to authenticate with the Briareus Server
- `logger` Logging Object. Must conform to the expected interface. See logging section below

#### Logging
The Briareus client requires a logging object. The logging object must conform to the following pattern. `logger.logLevel(data, message)`. Where `logLevel` is  `trace`, `debug`, `info`, `warn`, `error`, or `fatal`. `data ` is an map and `message` is a string.

Many logging modules provide this interface but `bunyan` is a nice library. A Bunyan logger that logs to standard out can be created like so:

```js
const bunyan = require('bunyan');
const logger = bunyan.createLogger({
  name: 'Briareus Client',
  level: 'warn',
  streams: [
    { stream: process.stdout }
  ]
});
```

See https://github.com/trentm/node-bunyan#readme for more information.

### Creating a Variant
```js
const briareus = new BriareusClient(options);

const params = {
  // Add params
};

briareus.variant.create(params, (err, resp) => {
  if (err) return cb(err);
  // Variant Created
});
```

#### Parameters
- `data` [map]: See Variant Schema https://github.com/bugcrowd/briareus/blob/master/lib/service/schemas/variant.js

### Creating a Deployment
```js
const briareus = new BriareusClient(options);

let params = {
  // Add params
}

briareus.variant.deployment.create(params, cb);
```

#### Parameters
- `slug` [string]: The human readable unique identifier belonging to the Variant you want to deploy to.
- `data` [map]: See Deployment Schema https://github.com/bugcrowd/briareus/blob/master/lib/service/schemas/deployment.js