Package: dockbot
# DockbotA continuous integration system which uses Docker and Buildbot.  Dockbot is aPython program which starts a **master** Docker instance and a number ofbuild **slaves**.  The **master** coordinates builds, offers a Web interfacefor monitoring and controlling builds and triggers builds based on changesto source repositories.  The **slaves** perform the builds under differentconfigurations.# InstallationYou can install dockbot with pip as follows:pip install dockbotOr from GitHub:git clone https://github.com/CauldronDevelopmentLLC/dockbotcd dockbotsudo python setup.py install# Configuring a Dockbot ProjectTo use dockbot you need to create a ``dockbot.json`` configuration file in adirectory of it's own and a number of **slaves** in a directory called``slaves``.  In the slave directories you also have ``dockbot.json`` fileswhich configure which projects the slave will run.  The directory structureshould look like this:dockbot.jsonlib/slaves/slave1/dockbot.jsonprojectA.dockerprojectB.docker...slave2/...slaveN/...The optional ``lib`` directory can contain Docker file fragments which may beused by multiple slaves.## Basic configurationThe top level ``dockbot.json`` file needs a some basic configurationinformation to setup the dockbot install:```"project": "Dockbot","url": "https://github.com/CauldronDevelopmentLLC/dockbot","namespace": "dockbot","admin": "Joseph Coffland <jcoffland@cauldrondevelopment.com>","ip": "127.0.0.1","http-port": 8049,"buildbot-port": 8050,```These configuration values have the following meanings:* project - The dockbot project name.* url - The project URL, cosmetic only.* namespace - A unique name prefix for docker images in this project.* admin - A email address, cosmetic only.* ip - The IP address to which ports should be bound.* http-port - The HTTP port for the build master's Web interface.* buildbot-port - Opening this port allows other build slaves to connect.## Build modesOften software can be built in more than one way.  Build modes make it possibleto configure different builds configurations for the same software.  Build modeconfiguration looks like this:```"modes": {"debug": {"scons": {"debug": 1}},"release": {}},```Above we configure two build modes ``debug`` and ``release``.  The names arearbitrary and can be anything you like.  The dictionaries under these namesoverride options specific to those moves.## Projects```"projects": {"_default_": {"compile": ["scons", "-k"],},"cbang": {"test": true,"repo": {"type": "git","url": "https://github.com/CauldronDevelopmentLLC/cbang","branch": "master"}}}```The ``projects`` section is a dictionary of project configurations.  The special``_default_`` section sets the default configuration options for all projects.Project names are arbitrary and may contain the following configuration options:* compile - The compile command.* test - If true testing should be performed after the build is complete* repo - The source repository configuration* type - One of ``git``, ``github`` or ``svn``* url - The repository url.* org - An organization, used only with ``github`` repos with out a ``url``.* user - The repo user name.* pass - The repo password, if needed.* branch - The repository branch.* deps - Projects which must be built first.* packages - A list of package types, appended to the compile command.* build - If false the build step is omitted.## SlavesA slave represents a particular build configuration.  Each slave has its owndirectory under ``slaves``.  The ``dockbot.json`` file in this directory definesone or more images that will be built and adds any extra configuration optionsparticular to the slave.## Slave ImagesA slave image is a Docker image which will be run in one or more **modes**.Images are defined in the slave's ``dockbot.json`` as follows:```"images": {"cbang": {"projects": ["cbang"]}}```In the above example one image ``cbang`` is defined with one project ``cbang``.The project must be defined in the top level ``dockbot.json``.  To build theimage dockbot will look for a file ``cbang.docker`` in the slave's directory.It will then process this file with ``m4`` to produce a final ``Dockerfile``used to build the image.  The ``m4`` preprocessor will combine Dockerfilefragments to create the complete ``Dockerfile``.  These fragments may existeither in the slave's own directory, in a top level ``lib`` directory or inthe dockbot default libs.An example project ``.docker`` file make look like this:```include(base.m4)include(slave.m4)`````base.m4`` is defined as:```FROM debian:testinginclude(debian.m4)include(boost-1.59.0.m4)include(buildbot.m4)include(gcc-4.8.m4)```Each of these ``include()`` lines references a docker file fragment located inone of the lib directories.# Building Dockbot ImagesTo build a dockbot image run the following command:dockbot build <image>Where ``<image>`` is the name of the image.  e.g.``dockbot-debian-testing-64bit-cbang``.  If the image is successfully build thenit can be started.To rebuild a dockbot image run the following:dockbot rebuild <image>This command first deletes the old build than builds it again applying anyconfiguration changes.  In order to do a rebuild all of the images's containersmust first be stopped.# Starting & Running MasterThe build master is a special docker container which coordinates the builds.Like the slaves it too must be built and run.  This is accomplished as follows:dockbot build masterdockbot start masterThe build master must be restarted whenever the dockbot configuration ischanged.  To stop the master run the following:dockbot stop master# Dockbot StatusTo view the status of the dockbot containers run the following:dockbot statusor simply:dockbotThis will list the status of all configured dockbot containers.  The full nameof container in the current dockbot project will be displayed on a linewith it's current status.  Possible status are:* **[Not Found]** - The container's image has not been built yet.* **[Built]** - The image has been built but the container does not yet exist.* **[Running]** - The container is currently running.* **[Offline]** - The container exists but is not currently running.* **[Building]** - The image is currently being built.* **[Starting]** - The container is starting.* **[Stopping]** - The container is stopping.* **[Deleting]** - The image is currently being deleted.To check the status of a particular dockbot container run:dockbot status <container>You can also view the complete configuration of a dockbot container like this:dockbot config <container># Shell AccessSome times it is desirable to login and inspect the contents of a container.This is a accomplished with the dockbot ``shell`` command:dockbot shell <container>If the image was previously built this will open a shell in the container.  Ifthe container was already running it will attach a new shell to the runningcontainer.# The Web InterfaceThe build master's Web interface makes it possible to monitor and controlbuilds.  To view the Web interface navigate a brower to the IP and portspecified in the top level ``dockbot.json`` file.  At least the build mastercontainer must be running.  Some slave containers should also be running tomake it useful.# Triggering BuildsBuilds may be manually triggered using dockbot's ``trigger`` command.  Thesyntax is:dockbot trigger <container> [project]If ``[project]`` is omitted all projects on the slave will be triggered.# Triggering Builds from GitHubTBD# Publishing BuildsThe last 5 completed builds are placed in ``run/buildmaster/builds/``.  Once allthe builds for a particular project are correct they can be published usingthe ``dockbot-publish`` tool.TBD# Publishing Builds to GitHubTBD