Bosco is a utility knife to help manage the complexity that using microservices, which naturally results in a large number of code repositories, brings with it. Inspired by the Github 'setup', e.g. can a developer run one simple command and get up and running?

Docs: https://bosco.readme.io/v0.4.0/docs/what-is-bosco

npm install bosco -g
bosco setup

It will ask initially for:

This is then saved in a configuration file locally on disk, default is in ~/.bosco/bosco.json, so all subsequent commands use it.

It will then ask for a team to start with, and a folder (referred to below as ) to link the team to (it will create it if it doesn't exist).

After this, do the following:

cd <folder>
bosco morning

At the end of this sequence of steps you will have:

• All of the projects checked out into your project folder.
• Any dependent modules linked between projects (e.g. if one repo is actually a module depended on by another).
• All projects fully npm installed.

bosco team setup
<select team>
<select folder>
cd <folder>
bosco morning

Bosco is built around the idea that you use github teams to manage groups of repositories. So, when you first run setup, Bosco will connect to Github, grab all of the teams that you belong to - across all organisations - and cache them locally.

It will then ask you to link a team to a workspace folder - this folder can be anywhere, but it just lets Bosco know that this is the place where that team lives, this then appears in the output of the command 'bosco team ls'.

[07:09:26] Bosco: I'm glad I didn't know you when I was a kid.
[07:09:26] Bosco: Initialised using [/Users/cliftonc/.bosco/bosco.json] in environment [local] with team [service]
[07:09:26] Bosco: Your current github organisations and teams
[07:09:26] Bosco:  - tes/southampton-buildings > /Users/cliftonc/work/resources
[07:09:26] Bosco:  - tes/staff > Not linked
[07:09:26] Bosco:  - tes/cms > Not linked
[07:09:26] Bosco:  - tes/twigkit > Not linked
[07:09:26] Bosco:  - tes/example > Not linked
[07:09:26] Bosco:  - tes/engineering > Not linked
[07:09:26] Bosco:  - tes/world-university-rankings > Not linked
[07:09:26] Bosco:  - tes/profiles > /Users/cliftonc/work/profiles
[07:09:26] Bosco:  - Calipso/owners > Not linked
[07:09:26] Bosco:  - tes/owners > Not linked

To link a workspace, simply:

bosco team ln tes/example .

This will link the team 'tes/example' into the current folder as its workspace.

Commands in Bosco are defined via specific command files within the 'commands' folder: https://github.com/tes/bosco/tree/master/commands.

To get a list of installed commands in your installation just type 'bosco':

┌────────────┬────────────────────────────────────────────────────────────┐
│ Core       │ Example                                                    │
├────────────┼────────────────────────────────────────────────────────────┤
│ team       │ bosco team sync | bosco team ls | bosco team ln <team> <dr>│
├────────────┼────────────────────────────────────────────────────────────┤
│ cdn        │ bosco cdn <minify>                                         │
├────────────┼────────────────────────────────────────────────────────────┤
│ clean      │ bosco clean -r <repoPattern>                               │
├────────────┼────────────────────────────────────────────────────────────┤
│ clone      │ bosco clone                                                │
├────────────┼────────────────────────────────────────────────────────────┤
│ commit     │ bosco commit -r <repoPattern> 'Commit Message'             │
├────────────┼────────────────────────────────────────────────────────────┤
│ config     │ bosco config set <key> <value> | bosco config show <key>   │
├────────────┼────────────────────────────────────────────────────────────┤
│ grep       │ bosco grep <patternToSearch>                               │
├────────────┼────────────────────────────────────────────────────────────┤
│ help       │ bosco help <command>                                       │
├────────────┼────────────────────────────────────────────────────────────┤
│ install    │ bosco install -r <repoPattern>                             │
├────────────┼────────────────────────────────────────────────────────────┤
│ setup      │ bosco setup                                                │
├────────────┼────────────────────────────────────────────────────────────┤
│ pull       │ bosco pull -r <repoPattern>                                │
├────────────┼────────────────────────────────────────────────────────────┤
│ pushall    │ bosco pushall -r <repoPattern>                             │
├────────────┼────────────────────────────────────────────────────────────┤
│ run        │ bosco run -r <repoPattern>                                 │
├────────────┼────────────────────────────────────────────────────────────┤
│ s3delete   │ bosco -e <environmment> s3delete <build>                   │
├────────────┼────────────────────────────────────────────────────────────┤
│ s3list     │ bosco -e <environment> s3list                              │
├────────────┼────────────────────────────────────────────────────────────┤
│ s3push     │ bosco -e <environment> -b <build> s3push <tag>             │
├────────────┼────────────────────────────────────────────────────────────┤
│ setup      │ bosco setup                                                │
├────────────┼────────────────────────────────────────────────────────────┤
│ stash      │ bosco stash -r <repoPattern>                               │
├────────────┼────────────────────────────────────────────────────────────┤
│ status     │ bosco status -r <repoPattern>                              │
├────────────┼────────────────────────────────────────────────────────────┤
│ stop       │ bosco stop -r <repoPattern>                                │
├────────────┼────────────────────────────────────────────────────────────┤
│ upstream   │ bosco upstream -r <repoPattern>                            │
└────────────┴────────────────────────────────────────────────────────────┘

To get help on any command just type;

bosco help s3push

You can use a number of parameters to control the behaviour of Bosco. Parameters are configuration options that can be used across commands.

To see all possible parameters, just type 'bosco'.

To enable bash completion for bosco, add the following line to your ~/.bashrc file:

eval "$(bosco --completion=bash)"

The default command, this sets you up.

bosco setup

This will sync with github, ask you for a default team and workspace folder, clone all the repositories in that team, auto link any dependent modules together (saving lots of 'npm link ../module', and then finally run npm install on all of them. This literally will save you hours of work on a larger project.

If any repository already exists locally it will skip it. Typically you only use this command once, and use the other pull, install, morning commands on a daily basis.

If services want to take part in the static asset part, they need a bosco-service.json config file.

e.g.

{
    "assets": {
        "basePath": "/src/public",
        "js": {
            "bottom": [
                "js/lib/base64.min.js",
                "js/lib/bind.shim.min.js",
                "js/lib/cookies.min.js",
                "js/lib/lean-modal.min.js",
                "js/report-review.js",
                "js/resources.js"
            ],
            "top": [
                "js/event-tracking.js"
            ]
        },
        "css": {}
    }
}

Some projects will want (or need) something more sophisticated than a simple concatenation / minification step for assets. To support this, Bosco allows you to define a build configuration on a per project basis in the bosco-service.json file.

For example, a project that uses Gulp to create assets as well as watch for change, can use a configuration like that below in the bosco-service.json:

{
    "build":{
        "command":"gulp build",
        "watch":{
            "command":"gulp build --watch",
            "ready":"Finished 'build'"
        }
    },
    "assets": {
        "basePath":"/dist",
        "js": {
            "upload": [
                "js/tsl-uploader.js"
            ]
        },
        "css": {
             "upload": [
                "css/tsl-uploader.css"
            ]
        },
        "images": {
            "upload" :[
                "img"
            ]
        }
    }
}

In this mode, instead of directly defining the JS and CSS assets, simply define a build configuration that includes the command to run before pulling together the assets, along with a watch command (if available).

The files created as a result of the build step should just be included as normal, but they won't be read until the build command is complete.

This will aggregate and serve all of the static assets (those defined within bosco-service.json files within each project) on a single pseudo CDN url.

bosco cdn <minify>

If passed the minify parameter it will minify the JS as it does if pushing to s3, but serve locally.

In CDN mode you can just visit the index page, default: Bosco Index and it will list all the files for you.

The html fragments for compoxure in local mode (or the raw asset files) can be built by following a simple convention:

http://localhost:7334/<environment>/<build>/html/tag.type.html

For example:

• http://localhost:7334/local/default/html/bottom.js.html

This would contain a fragment that has script tags for all of the JS tagged in the bottom group.

You can view all assets that are being tracked by bosco cdn by going to any url once the bosco cdn command is running and using the cdn port (i.e: 127.0.0.1:7334). You can also see a list of repos by going to /repos on the bosco cdn server (i.e: 127.0.0.1:7334/repos).

This will create bundles for front end assets (JS, CSS, Templates), this command can be run across repositories in a workspace, but it is typically run within a single service (hence the -s parameter below) by a build server that dynamically assigns a build number.

bosco s3push -s -e <environment> -b <buildnumber>

This command requires that you have configured your AWS details for S3. Best to put these into a .bosco folder in the project workspace a per environment config, e.g. .bosco/tes.json.

{
    "aws":{
      "key": "XXXXXX",
          "secret": "XXXXXX",
          "bucket": "bucket-name",
          "region": "eu-west-1",
          "cdn":"https://dudu89lpwit3y.cloudfront.net"
    }
}

To then access the html fragments for compoxure, it follows a simple convention:

<cdn>/<environment>/<build>/<type>/<bundle>.<fragmentType>.<js|css|html|map|txt>

For example:

• https://dudu89lpwit3y.cloudfront.net/tes/55/html/bottom.js.html

This would contain a fragment that has script a tag for all of the minified JS tagged in the bottom group.

To ensure that we always know what was in a specific release, the minification process creates a manifest file for each bundle that includes each file, along with the last commit that was made to that file.

Before you push, it will do a diff between the last manifest file created, and the one for the bundle you are about to push, and ask you to confirm that all of the files changed are ones that you expected to be changed. e.g. it will try to avoid you pushing someone elses change unexpectedly.

service-hub-beta/js/lib/html5shiv-min.js, Last commit: 09b61e7 refactor
service-hub-beta/js/lib/jquery-1.11.0-min.js, Last commit: 09b61e7 refactor
service-hub-beta/js/lib/jquery-mobile-1.4.3-min.js, Last commit: 09b61e7 refactor
service-hub-beta/js/lib/modernizr-2.7.1-min.js, Last commit: 09b61e7 refactor
service-hub-beta/js/dom.js, Last commit: 09b61e7 refactor
service-hub-beta/js/measure.js, Last commit: 09b61e7 refactor
service-hub-beta/js/page.js, Last commit: 2353274 @doodlemoonch @csabapalfi fix broken browse section height
service-hub-beta/js/resource.js, Last commit: 09b61e7 refactor
service-hub-beta/js/sequence.js, Last commit: 09b61e7 refactor
service-hub-beta/js/upload.js, Last commit: 09b61e7 refactor
service-resource/js/lib/base64.min.js, Last commit: 29bba10 @antony @tepafoo Moved own resource logic to front-end
service-resource/js/lib/bind.shim.min.js, Last commit: e1b212b @antony User cannot review their own resource.
service-resource/js/lib/cookies.min.js, Last commit: 29bba10 @antony @tepafoo Moved own resource logic to front-end
service-resource/js/lib/lean-modal.min.js, Last commit: 8ba20d1 @antony Fire a modal when reporting a review
service-resource/js/report-review.js, Last commit: e0c5af0 @antony @carolineBda Feedback / Report review form
service-resource/js/resources.js, Last commit: bf28fc9 @cressie176 fixing server side use of authentication state

Bosco will attempt to detect duplicate files (via a checksum), as well as duplicate libraries (e.g. multiple versions of jQuery). If it spots a duplicate, it will not add it to a minified bundle after warning you that it found it. Because of this the first version of a library it finds will 'win'.

It is strongly recommended that you pull all 'core' libraries like jQuery into a central single project to avoid duplication, but Bosco will try and help you if you don't.

Note that if you use the external build option then the files inside this project don't get included in the duplicate check.

To create your own Bosco commands for your project (ones that you don't want to submit back to core via a pull request), simply create a 'commands' folder in the root of your Bosco workspace and add commands to it. You can use any of the core commands as a starting point.

At TES we have a github project that is a 'default' Bosco workspace that contains local commands and configuration that teams use as their workspace.

You can create bosco commands as npm packages and install it via npm (local or global). These commands must be named bosco-command-command such as bosco-command-ports. Bosco will try to find such commands as long as they match the naming pattern. This was inspired by Yeoman generators

There are two ways of passing input through to a command: options and args.

Options are specified via - switches, and are typically applied across more than one command. For example, -e development.

bosco -e development s3push
bosco -e development cdn minify

Bosco commands can specify one or more options they are interested in and they will be parsed at runtime. You can see an example on the activity command source file.

Within a command these are then accessed via the global Bosco object, by their long name (see /bin/bosco.js).

var environment = bosco.options.environment;

Arguments are an array of strings that follow the command.

For example:

bosco cdn minify

In the above command, the command is cdn, the args are: ["minify"]

To use in a command, you typically scan the array for their presence and set a variable (as in most instances they actually represent a Boolean vs a string).

var minify = _.contains(args,'minify');