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

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:

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

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

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