0.1.5 • Public • Published

    Project Venice

    Venice encapsulates a series of tools, practices and systems to make software development simpler, easier and more standardized.

    It was born of questions such as: "Wouldn't it be great if we could easily deploy this thing for QA?" "How can we version these deliverables?" "Why is it so hard to test each PR?"

    These are the 10 governing principles behind venice:

    1. A build always start from a clean slate - dependent packages changed? New things need to be installed? All of these will stand up when starting each build from scratch.
    2. Building and testing is a locally-reproducible step - wondering why a build works locally but fails on the CI? No problem: just run the very same environment locally and debug it.
    3. Every PR is built and tested - get immediate feedback at the PR level. If a regression is introduced, it will show on the PR itself. No more guessing.
    4. Functional branches are deployment-ready - when pull requests are merged into main branches, these branches’ builds become potentially deployable packages.
    5. Multiple functional branches - in some cases, there are several work streams that may need to be deployed independently (i.e. maintenance vs. new features). Each functional branch represents a deployment-ready build.
    6. Versioning is flexible but its absence is non-negotiable - each deployable build is properly versioned, tagged, and uploaded to github accordingly. The absence of versioning is not an option.
    7. Deployment pipeline is a necessity - a build can be automatically deployed to a constant deployment environment or manually deployed in cases of QA or production environments. Need to roll some version back? Totally possible.
    8. Multiple deployment environments per functional branch - besides having an automatically deployable environment, each functional branch can have many other environments making your system deployable on a cross-functional/cross-environment way.
    9. Reuse of good practices and tools - the practices employed on venice are tested and proven. Build steps and deployment systems can be reused and adapted over and over across projects.
    10. You do the creative work, bots do the heavy lifting - focus on creating the best code out there and leave the heavy lifting of building, reporting and deploying to bots.

    Installing the Venice CLI (Basic)

    Venice relies on other opens source softwares to run. If you are a developer you probably already have those installed, if you not you will need (in order):

    Basic installation:

    • Download node v6.x.x from the official website and install it. This installation will also install npm for you.
    • Download git (latest) from the official website and install it.

    Advanced installation:

    • brew(latest) Installation Instructions
    • nvm (latest) Install running: brew install nvm
    • node (v6.x.x) and npm (v3.x.x) Install running: E.g nvm install 6.7.0
    • git (v2.5.0) Install running brew install git

    Finally, after following either the basic or advanced installation guide, install venice running:

    npm install -g @workco/venice

    Venice relies heavily on docker instances, you may need to install docker (version 1.12.1) and docker-compose (version 1.8.0) for some features. You can download and install here. If you are interested in development of Venice CLI, read the section Other venice dependencies (developers) at the end of this document.

    Overview of Venice commands

    Venice help

    If you need help, you can print instructions of the available commands using:

    venice -h

    ProTip: You can print the help of venice subcommands as well (e.g. venice login -h, venice create -h, etc.)


    Venice requires you to use your github user. As such, it will need access to your github account. Check at how to create an access token for command-line usage on github's documentation. We recommend creating a token with all access rights.

    In order to login to Venice you simply run:

    venice login --server <server> --user <user> --token <token>


    • <server> is your Venice server (i.e. venice.mydomain.com)
    • <user> is your Github users (ie. masterdeveloper)
    • <token> is your Github access token (ie. 974bq13448d70ca3fae0e9cd8d02d9d1d68b3ab5)

    Once logged in, all your subsequent commands will be sent to your Venice server.

    DevTip: The credentials are saved in a dotfile .venice in the user home directory.


    In order to log out, simply:

    venice logout

    Your credentials will be deleted and you will need to login before using other venice commands.


    Venice call "builds" published tags on GitHub. A build is created automatically when a push is done in one of the monitored branches (explained below). In order to see all published tags/releases use the following git command, inside the project folder.

    git log -n 10 --oneline --decorate --tags --no-walk


    The command to deploy a project is:

    venice deploy --build <build> --env <env> --branch <branch>


    • <build> is a tag (i.e. feature-x-1.0.0-build.3)
    • <env> is one of the environments defined in venice.json (i.e. qa)
    • <branch> (Optional) is the branch that should be deployed. If not provided, it will be inferred from the build name

    Upon success you will receive a message that the build process has started.


    Once logged in, you can create Venice-based project with:

    $ venice create --name <name>


    • <name> is the name of the project you want to create

    This should be executed only once, during the creation of each project.


    $ venice create my-proj
    created my-proj
    $ cd my-proj/
    $ ls -la
    total 8
    drwxr-xr-x  3 tiagoluchini  staff   102 Sep  2 22:59 .
    drwxr-xr-x  8 tiagoluchini  staff   272 Sep  2 22:59 ..
    -rw-r--r--  1 tiagoluchini  staff  1184 Sep  2 22:59 venice.json
    -rw-r--r--  1 tiagoluchini  staff   474 Sep  2 22:59 docker-compose.yml
    -rw-r--r--  1 tiagoluchini  staff   975 Sep  2 22:59 Dockerfile

    Fine tuning your project

    As you can see, the my-proj folder was created alongside a GitHub repo. Inside the project folder a few configuration files were also created.

    The file called venice.json is the main touch of point between your project and the Venice system. The full documentation for venice.json can be found here.

    The other two files (Dockerfile and docker-compose.yml) are respectively your build system and your services description. We'll get to those soon.

    For now take a look at the basic document created by venice create:

    $ cat venice.json
      "description": {
        "project": "my-proj",
        "type": "smart"
      "build": {
        "steps": [
        "artifacts": {
          "path": "dist/"
        "versioning": {
          "type": "npm"
        "branches": {
          "master": {
            "version": "1.0.0"
      "deploy": {
        "service": "web-server",
        "environments": {
          "cd": "auto",
          "qa": "manual"
      "reporter": {
        "type": "slack",
        "channel": "venice-test-bot"

    The file is divided in four major sections:

    • description: generic details about the project
    • build: instructions on how to build, branches being monitored, test and where artifacts are
    • deploy: how to version, where to deploy and which branches need to be monitored for deployment
    • reporter: how does the bots communicate back with users


    All the following commands will be executed based on the project folder that you are calling them. There are three options to see the build output:

    • venice log (will run venice log --live by default)
    • venice log --live

    Live log for the current build. Running this command will block your terminal and print the log messages as they are appear during the build step. When you are done, press ctrl + c to have your terminal back.

    • venice log --pr (will return the log of the last PR as default)
    • venice log --pr <PR#>
    • venice log --build (will return the log of the last push as default)
    • venice log --build <tag>

    Constant build/test settings

    The build section of the venice.json file specifies the steps the build bot will follow to check, build, and test your project. Each step is the name of a docker-compose.yml service. Each step is run in sequence and only if the previous step ran successfully.

    The default docker-compose.yml file looks like this:

    $ cat docker-compose.yml
      image: workco-commit-checker
      build: .
      command: ['/tmp/run.sh']
      dockerfile: ./docker/Dockerfile-builder
        - .:/workdir
      image: busybox
        - /disk
      build: .
      dockerfile: ./docker/Dockerfile-web-server

    TBD: validate this file

    TBD: describe better some of the sessions/settings

    TBD: show different possibilities

    Other venice dependencies (developers)

    In order to develop for venice-cli you will need:

    • All dependencies of section Installing the Venice CLI (Basic)
    • yarn (latest) Install with npm install -g yarn

    Development instructions:

    • Clone the Venice CLI repository
    • To install the dependencies run: yarn
    • Venice CLI is written in ES6, so in order to run its code to test locally during development, you need to run npm run build. This will create a dist folder with ES5 JS and then you can node ./dist/venice.js

    ProTip: alias venice="npm run build && node dist/venice.js" This creates a temporary venice alias that will build and run the current code without cluttering your command line of commands. Very helpful when developing a CLI.

    The Venice Server

    Venice CLI relies on a running server. More documentation about setting up a server is found at the Venice core documentation.

    Deployment settings

    TBD: explain versioning

    TBD: explain target

    TBD: exaplin branch monitoring

    TBD: explain manual releasing

    All project repos

    https://github.com/workco/venice-cli https://github.com/workco/venice-core




    npm i @workco/venice

    DownloadsWeekly Downloads






    Last publish


    • caldenwco
    • oliverdore
    • barbieri-workco
    • igoroliveira
    • joshrounsville