dab

Dab

standard-readme compliant GitHub license CircleCI Build Status Gitter chat

The Developer lab.

Try in PWD

Dab is a flexible tool for managing multiple interdependent projects and their orchestration, all while providing a friendly user experience and handy devops tools.

Table of Contents

Install

Simply download the dab wrapper script to somewhere in your PATH environment variable, for example:

 $ sudo curl https://raw.githubusercontent.com/Nekroze/dab/master/dab -o /usr/local/bin/dab
 $ sudo chmod 755 /usr/local/bin/dab

After this the dab command should be available in your shell:

 $ dab completion

If you are an OSX user you will want to set the DAB_GID environment variable to 0 to avoid docker access issues and the DAB_AUTOUPDATE_COMPLETION environment variable to false as completion is only supported on Linux out of the box.

Usage

You need only have docker installed and any POSIX compliant shell to run the wrapper scripts and get going with dab. This will start the dab container and forward all arguments into it:

 $ dab --help

If you do not need to build the docker image yourself and just want to use dab, the dab script we just executed is all that is needed and can be used from (or moved to) any location.

It is recommended you add the directory containing the dab script to your shell’s PATH environment variable.

If you want to execute dab with sudo and retain set environmental variables, you can use the following to execute dab:

 $ sudo -E dab --help

Stable Updates Stream

The latest image is built off of the ever changing master branch. While all efforts are made to keep the UI and behaviour stable, you may wish to use the stable docker tag (and thus git branch) which receives periodic merges from the master branch.

You can control the image to be used with the DAB_IMAGE_TAG environment variable like so:

export DAB_IMAGE_TAG=stable

Demoing

If you are not yet sure if Dab is right for you, Play With Docker (PWD) will allow you to spin up a temporary cloud server with Dab available. You will be presented with a terminal containing the latest version of Dab ready to use.

Setting up a project

As a developer I work on a heaps of projects each with their own needs and quirks. Lets use dab to manage a project for us, first we need to register its existence:

 $ dab repo add containaruba https://github.com/Nekroze/containaruba.git

This will register the containaruba repository and attempt to clone it into $DAB_REPO_PATH which defaults to ~/dab.

Now we can set the type of entrypoint we want this repo to use.

 $ dab repo entrypoint create containaruba
 $ dab config add repo/containaruba/entrypoint/start ./test.sh

Now whenever we start this repo, or a repo that depends upon this one, the test.sh script within the root of the containaruba repo will be executed.

 $ dab repo entrypoint start containaruba

Using dockerized apps

There is an ever growing selection of tools and services dab provides (checkout dab apps list) for recording metrics, databases, etc.

 $ dab apps start grafana
 $ dab apps start ntopng
 $ dab apps start redis

Updating

Dab has a self updating mechanism in that it will pull the latest version of the dab image when dab is next executed a day or more after the last time it checked. So generally you do not have to do anything at all to stay up to date with the latest features, bug fixes, and security improvements. This new image will update the wrapper script if necessary.

Watching and Learning

The Dab UX project stores user experience tests that should almost always be added to and not modified or removed. This allows for a stable command line interface with a clear notification if that interface changes in the form of changes to that project. Each version of Dab itself is tested against the current tests in Dab UX before released to ensure no regression. These tests are also used to generate the Dab UX Website where you can learn more about what Dab can do for you.

Features

Customization

Dab supports various means of customization primarily through environment variables.

Any exported environment variable starting with DAB_ will be passed into any dab container by the wrapper. You can also set environment variables without altering your shell(s) by writing to the dab config. For example any file in the config directory (defaults to ~/.config/dab but customizable via the $DAB_CONF_PATH environment variable) under a directory called environment (so ~/.config/dab/environment by default) will be loaded as Dab starts into env vars where the filename is the name of the env var and the contents of the file its value.

Once you are passing in environment variables they can be used to tweak a great many knobs. For example most dockerized apps can have their version changed or their settings altered, try dab apps config to explore your options.

The following is an (incomplete) list of environment variables dab knows about and what they do:

The environment can be further customized by setting specific config keys.

Contributing

If you would like to help hone dab into a better tool check out our contributing documentation.

Bill Of Materials

The following projects are used to write dab:

Maintainers

Contributing

See the contributing file!

Pull Requests accepted without corresponding issues provided they are well explained and reasoned.

Small note: If editing the README, please conform to the standard-readme specification.

License

GPLv3 © 2018 Taylor Lawson

This site is open source. Improve this page.