Merge pull request #30 from mnordsletten/master

Bobs & Builders: Added docs on B&B

Mothership-server.rst

@@ -73,16 +73,19 @@ Server options
 To provide options to mothership there are two possibilities:
 
 1. Launch parameters to ``mothership serve``. Options use the ``--<option>`` format.
-2. Options in config file: ``config_files/config.yaml`` supplied in a ``key: value``.
+2. Options in config file, default location: ``config_files/config.yaml`` supplied in a ``key: value``.
 
 Notable options are::
 
+      --name string                  Name that Mothership reports back
       --certfile string              Certificate file for TLS
       --clean                        <bool, optional> clean everything
       --keyfile string               Private key file for TLS
       --serverauth string            server auth method (default "none")
       --serverport string            port number (default "8080")
       --verboselogging               <bool, optional> verbose logging
+      --dockeroptions                Options to use when building in docker inside Mothership
+      --config                       Manually provided path to config file
 
 If you want to run the Mothership in Docker but want to change some of the default settings mentioned above, you just
 add :code:`serve` at the end, followed by the Mothership options you want to change or add:
@@ -100,3 +103,77 @@ add :code:`serve` at the end, followed by the Mothership options you want to cha
 
 Bobs and Builders
 -----------------
+
+In order to build images with specific versions of IncludeOS there was a need to create a new system. In addition there needed to be a way to manage these different Builders. Therefore the following terms have been introduced into Mothership:
+
+.. glossary::
+
+Builder
+  A Builder is able to produce images with **one** specific version of IncludeOS. All Builders are by definition ready to be used.
+  The Builder is used to perform the following two actions:
+
+    #. Build IncludeOS images
+    #. Perform NaCl validation
+
+Bob
+  A Bob is an abstraction for a resource that can become a Builder. In order for the Bob to become a Builder it needs to be prepared, this could mean it needs to be installed or downloaded.
+
+BobProvider
+  A BobProvider is a resource which provides Bobs. These Bobs can be prepared to become Builders.
+
+Both Bobs and Builders have the following information:
+
+    ID
+      ID of the Bob/Builder. Used in all API calls when it is required to specify a Bob/Builder.
+    Name
+      Name of the Bob/Builder.
+    Version
+      The version tag that IncludeOS images built with this Bob/Builder will report as its version.
+    VcsRef
+      The Git commit that the IncludeOS version was built from
+    BuildDate
+      The date of the last Git commit.
+    ProviderID
+      Which provider the Bob/Builder comes from.
+
+Usage and examples
+~~~~~~~~~~~~~~~~~~
+
+Example 1: Preparing a Builder
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In order to prepare a Builder the following tasks must be completed:
+
+  #. Get list of available BobProviders::
+
+      /v1/bobproviders
+
+  #. Update one of the Bobproviders, here ``DockerHub`` is chosen::
+
+      /v1/bobproviders/DockerHub/update
+
+  #. Get list of available Bobs from the ``DockerHub`` provider::
+
+      /v1/bobproviders/DockerHub/bobs
+
+  #. Prepare a specific Bob with ID ``idNum1`` and turn it into a Builder::
+
+      /v1/bobproviders/DockerHub/prepare/bobs/idNum1
+
+  #. Check list of Builders::
+
+      /v1/builders
+
+
+Example 2: Building and validating NaCls
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To perform actions with a specific Builder the ID is required.
+
+If we wanted to build with the Builder from example 1 we would have to call::
+
+  /v1/images/build/services/Starbase/builders/idNum1
+
+To validate a NaCl the following endpoint would be called::
+
+  /v1/nacls/validate/builders/idNum1

Quick-start.rst

@@ -63,7 +63,7 @@ The options used are::
     Then the mothership options:
         mothership serve                    Start mothership server
 
-.. note:: If you are experiencing problems with permissions for the mounted resources you might need to launch the docker container with ``--privileged``. On systems like RedHat Enterprise Linux that use SELinux this might be necessary.
+.. note:: If you are experiencing problems with permissions for the mounted resources you might need to launch the docker container with ``--privileged``. On systems like RedHat Enterprise Linux that use SELinux this might be necessary. This will need to be sent to the inside as well by using ``--dockeroptions "--privileged"`` as a Mothership option as well. 
 
 This will launch the mothership server. Make sure there are no errors in the launch output and the following lines indicate that basic auth and TLS are properly configured::