Merge "Fuel documentation ready for review"

9 files changed, 283 insertions, 133 deletions

diff --git a/fuel/LICENCE b/fuel/LICENCE
deleted file mode 100644
index 8b13789..0000000
--- a/fuel/LICENCE
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/fuel/LICENSE.rst b/fuel/LICENSE.rst
new file mode 100644
index 0000000..9537658
--- /dev/null
+++ b/fuel/LICENSE.rst
@@ -0,0 +1,85 @@
+Copyright 2015 Open Platform for NFV Project, Inc. and its contributors
+
+Open Platform for NFV Project Software Licence
+==============================================
+Any software developed by the "Open Platform for NFV" Project is licenced under the
+Apache License, Version 2.0 (the "License");
+you may not use the content of this software bundle except in compliance with the License.
+You may obtain a copy of the License at <http://www.apache.org/licenses/LICENSE-2.0>
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+Open Platform for NFV Project Documentation Licence
+===================================================
+Any documentation developed by the "Open Platform for NFV Project"
+is licensed under a Creative Commons Attribution 4.0 International License.
+You should have received a copy of the license along with this. If not,
+see <http://creativecommons.org/licenses/by/4.0/>.
+
+Unless required by applicable law or agreed to in writing, documentation
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+Other applicable upstream project Licenses relevant for Fuel@OPNFV
+==================================================================
+You may not use the content of this software bundle except in compliance with the
+Licenses as listed below:
+
++----------------+-----------------------------------------------------+
+| **Component**  | **Licence**                                         |
++----------------+-----------------------------------------------------+
+| OpenStack      | Apache License 2.0                                  |
+|                | https://www.apache.org/licenses/LICENSE-2.0         |
++----------------+-----------------------------------------------------+
+| OpenDaylight   | Eclipse Public License 1.0                          |
+|                | https://www.eclipse.org/legal/epl-v10.html          |
++----------------+-----------------------------------------------------+
+| PostgreSQL     | PostgreSQL Licence:                                 |
+|                | http://opensource.org/licenses/postgresql           |
++----------------+-----------------------------------------------------+
+| MongoDB        | GNU AGPL v3.0.                                      |
+|                | http://www.fsf.org/licensing/licenses/agpl-3.0.html |
++----------------+-----------------------------------------------------+
+| CoroSync       | BSD 2-Clause                                        |
+|                | http://opensource.org/licenses/bsd-license.php      |
++----------------+-----------------------------------------------------+
+| Pacemaker      | GPL v2                                              |
+|                | https://www.gnu.org/licenses/gpl-2.0.html           |
++----------------+-----------------------------------------------------+
+| RabbitMQ       | Mozilla Public License                              |
+|                | https://www.rabbitmq.com/mpl.html                   |
++----------------+-----------------------------------------------------+
+| Linux          | GPLv3                                               |
+|                | https://www.gnu.org/copyleft/gpl.html               |
++----------------+-----------------------------------------------------+
+| Docker         | Apache License 2.0                                  |
+|                | https://www.apache.org/licenses/LICENSE-2.0
++----------------+-----------------------------------------------------+
+| Fuel           | Apache License 2.0                                  |
+|                | https://www.apache.org/licenses/LICENSE-2.0         |
++----------------+-----------------------------------------------------+
+| OpenJDK/JRE    | GPL v2                                              |
+|                | https://www.gnu.org/licenses/gpl-2.0.html           |
++----------------+-----------------------------------------------------+
+| Ceph           | GPL v2                                              |
+|                | https://www.gnu.org/licenses/gpl-2.0.html           |
++----------------+-----------------------------------------------------+
+| Puppet         | Apache License 2.0                                  |
+|                | https://www.apache.org/licenses/LICENSE-2.0         |
++----------------+-----------------------------------------------------+
+| Cobbler        | GPL v2                                              |
+|                | https://www.gnu.org/licenses/gpl-2.0.html           |
++----------------+-----------------------------------------------------+
+| Nailgun        | Apache License 2.0                                  |
+|                | https://www.apache.org/licenses/LICENSE-2.0         |
++----------------+-----------------------------------------------------+
+| Astute         | Apache License 2.0                                  |
+|                | https://www.apache.org/licenses/LICENSE-2.0         |
++----------------+-----------------------------------------------------+
+
diff --git a/fuel/TODO b/fuel/TODO
index 906dfb5..7aa42d2 100644
--- a/fuel/TODO
+++ b/fuel/TODO
@@ -4,6 +4,7 @@
 #########################################################################
 Following items needs to be done to achieve an OPNFV/BGS ARNO Fuel Stack:
 1) Add support for CentOS 6.5 - REMAINING
-2) Add Autodeployment "deploy.sh" for Jenkins
-3) Dry-run Funktest (Jenkins/Robot/etc.)
-4) Finalize Documentation
\ No newline at end of file
+2) Add Local GIT repo mirror
+3) Add Auto-deployment for Linux-Foundation Lab.
+4) Dry-run Funktest (Jenkins/Robot/etc.)
+5) Finalize Documentation
\ No newline at end of file
diff --git a/fuel/docs/src/build-instructions.rst b/fuel/docs/src/build-instructions.rst
new file mode 100644
index 0000000..e923cab
--- /dev/null
+++ b/fuel/docs/src/build-instructions.rst
@@ -0,0 +1,177 @@
+:Authors: Jonas Bjurel (Ericsson)
+:Version: 0.1.0
+
+================================================================
+OPNFV Build instructions for - < Component denomination >
+================================================================
+
+Abstract
+========
+
+This document describes how to build <Component>, build system dependencies and required system resources.
+
+License
+=======
+Fuel@OPNFV DOCs (c) by Jonas Bjurel (Ericsson AB)
+
+Fuel@OPNFV DOCs (c) is licensed under a Creative Commons Attribution 4.0 International License. You should have received a copy of the license along with this. If not, see <http://creativecommons.org/licenses/by/4.0/>.
+
+
+**Contents**
+
+1   Version history
+
+2   Introduction
+
+3   Requirements
+
+4   Building
+
+5   Artifacts
+
+
+1   Version history
+===================
+
++--------------------+--------------------+--------------------+--------------------+
+| **Date**           | **Ver.**           | **Author**         | **Comment**        |
+|                    |                    |                    |                    |
++--------------------+--------------------+--------------------+--------------------+
+| 2015-04-23         | 0.1.0              | Jonas Bjurel       | First draft        |
+|                    |                    |                    |                    |
++--------------------+--------------------+--------------------+--------------------+
+
+2   Introduction
+================
+
+This document describes build system used to build Fuel@OPNFV, required dependencies and minimum requirements on the host to be used for the buildsystem.
+
+The Fuel build system is desigened around Docker containers such that dependencies outside of the build system can be kept to a minimum. It also shields the host from any potential dangerous operations performed by the build system.
+
+The audience of this document is assumed to have good knowledge in network and Unix/Linux administration.
+
+3   Requirements
+================
+
+3.1 Minimum Hardware Requirements
+---------------------------------
+
+- An x86_64 host (Bare-metal or VM) with Ubuntu 14.04 LTS installed
+
+- ~30 GB available disc
+
+- 4 GB RAM
+
+3.2 Minimum Software Requirements
+---------------------------------
+
+The build host should run Ubuntu 14.04 operating system.
+
+On the host, the following packages must be installed:
+
+- docker - see https://docs.docker.com/installation/ubuntulinux/ for installation notes for Ubuntu 14.04. Note: only use the Ubuntu stock distro of Docker (docker.io)
+
+- git (simply available through sudo apt-get install git)
+
+- make (simply available through sudo apt-get install make)
+
+- curl (simply available through sudo apt-get install curl)
+
+3.3 Preparations
+----------------
+
+3.3.1 Setting up the Docker build container
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+After having installed Docker, add yourself to the docker group:
+
+<usermod -a -G docker [userid]>
+
+Also make sure to define relevant DNS servers part of the global dns chain in
+in your </etc/default/docker> configuration file, eg.
+
+<DOCKER_OPTS=" --dns=8.8.8.8 --dns=8.8.8.4">
+
+Then restart docker:
+
+<sudo service docker.io restart>
+
+3.3.2 Setting up OPNFV Gerrit in order to being able to clone the code
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+- Start setting up OPNFV gerrit by creating a SSH key (unless you don't already have one), create one with ssh-keygen
+
+- Add your generated public key in OPNFV Gerrit <https://gerrit.opnfv.org/>
+  (this requires a linuxfoundation account, create one if you do not already have one)
+
+- Select "SSH Public Keys" to the left and then "Add Key" and paste your public key in.
+
+3.3.3 Clone the OPNFV code git repository
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Now it is time to clone the code repository:
+
+<git clone ssh://[Linux foundation user]@gerrit.opnfv.org:29418/genesis>
+
+Now you should have the OPNFV genesis repository with Fuel@OPNFV stored locally on your build host.
+
+4   Building
+============
+
+There are two methods available for building Fuel@OPNFV:
+
+- A low level method using Make
+
+- An abstracted method using build.sh
+
+4.1  Configure your build environment
+-------------------------------------
+
+Select the versions of the components you want to build by editing the fuel/build/config.mk file.
+Note if you want to build with OpenDaylight SDN controller you need to uncomment the lines starting
+with odl-main and java-main
+
+4.2  Low level build method using make
+--------------------------------------
+The low level method is based on Make:
+
+From the <fuel/build directory> invoke <make [target]>
+
+Following targets exist:
+
+- none/all -  this will:
+
+  - If not allready existing, initialize the docker build environment
+
+  - If not already done, build OpenDaylight from upstream (as defined by fuel-build config-spec)
+
+  - If not already done, build fuel from upstream (as defined by fuel-build/config-spec)
+
+  - Build the defined additions to fuel (as defined by the structure of this framework)
+
+  - Apply changes and patches to fuel (as defined by the structure of this framework)
+
+  - Reconstruct a fuel .iso image
+
+- clean - this will remove all artifacts from earlier builds.
+
+If the build is successful, you will find the generated ISO file in the <fuel/build/release> subdirectory!
+
+4.3  Abstracted build method using build.sh
+===========================================
+The abstracted build method useses the <fuel/ci/build.sh> script which allows you to:
+
+- Create and use a build cache - significantly speeding up the buildtime if upstream repositories have not changed.
+
+- push/pull cache and artifacts to an arbitrary URI (http(s):, file:, ftp:)
+
+For more info type <fuel/ci/build.sh -h>.
+
+5   Artifacts
+=============
+
+The artifacts produced are:
+
+- <OPNFV_XXXX.iso> - Which represents the bootable Fuel@OPNFV image, XXXX is replaced with the build identity provided to the build system
+
+- <OPNFV_XXXX.iso.txt> - Which holds version metadata.
+
+6  References
+=============
diff --git a/fuel/docs/src/installation-instructions.rst b/fuel/docs/src/installation-instructions.rst
index 234dfc2..05f56f3 100644
--- a/fuel/docs/src/installation-instructions.rst
+++ b/fuel/docs/src/installation-instructions.rst
@@ -1,5 +1,5 @@
 :Authors: Jonas Bjurel (Ericsson AB)
-:Version: 0.0.1
+:Version: 0.0.2
 
 ================================================
 OPNFV Installation instructions for - Fuel@OPNFV
@@ -14,7 +14,7 @@ License
 =======
 Fuel@OPNFV DOCs (c) by Jonas Bjurel (Ericsson AB)
 
-Fuel@OPNFV DOCs are licensed under a Creative Commons Attribution 4.0 Unported License. You should have received a copy of the license along with this. If not, see <http://creativecommons.org/licenses/by/4.0/>.
+Fuel@OPNFV DOCs are licensed under a Creative Commons Attribution 4.0 International License. You should have received a copy of the license along with this. If not, see <http://creativecommons.org/licenses/by/4.0/>.
 
 
 **Contents**
@@ -47,6 +47,9 @@ Fuel@OPNFV DOCs are licensed under a Creative Commons Attribution 4.0 Unported L
 | 2015-04-15         | 0.0.1              | Jonas Bjurel       | First draft        |
 |                    |                    | (Ericsson AB)      |                    |
 +--------------------+--------------------+--------------------+--------------------+
+| 2015-04-23         | 0.0.2              | Jonas Bjurel       | Minor changes      |
+|                    |                    | (Ericsson AB)      |                    |
++--------------------+--------------------+--------------------+--------------------+
 
 
 2   Introduction
@@ -231,8 +234,8 @@ This section describes the installation of the Fuel@OPNFV installation server (F
 
 14. Select network mode.
 
-    - Select Neutron with VLAN segmentation 
-    
+    - Select Neutron with VLAN segmentation
+
     ** Note: This will later be overridden to VXLAN by OpenDaylight.**
 
 15. Select Storage Backends.
@@ -311,13 +314,13 @@ This section describes the installation of the Fuel@OPNFV installation server (F
 31. Assign roles.
 
     - Check <Controller and Telemetry MongoDB>.
-    
+
     - Check the three servers you want to be installed as Controllesr in pane <Assign Role>.
 
     - Click <Apply Changes>.
- 
+
     - Check <Compute>.
- 
+
     - Check nodes to be installed as Compute nodes in pane Assign Role.
 
     - Click <Apply Changes>.
@@ -327,7 +330,7 @@ This section describes the installation of the Fuel@OPNFV installation server (F
     - Check Select <All> to select all nodes with Control, Telemetry . MongoDB and Compute node roles.
 
     - Click <Configure Interfaces>
-    
+
     - Screen Configure interfaces on number of <number of nodes> nodes is shown.
     - Assign interfaces (bonded) for mgmt-, admin-, private-, public- and storage networks
 
diff --git a/fuel/docs/src/release-notes.rst b/fuel/docs/src/release-notes.rst
index 467de6e..221b7f7 100644
--- a/fuel/docs/src/release-notes.rst
+++ b/fuel/docs/src/release-notes.rst
@@ -1,5 +1,5 @@
 :Authors: Jonas Bjurel (Ericsson)
-:Version: 0.1
+:Version: 0.2
 
 ================================================================
 OPNFV Release Note for "Arno-RC2 release candidate" - Fuel@OPNFV
@@ -14,7 +14,7 @@ License
 =======
 Fuel@OPNFV DOCs (c) by Jonas Bjurel (Ericsson AB)
 
-Fuel@OPNFV DOCs are licensed under a Creative Commons Attribution 4.0 Unported License. You should have received a copy of the license along with this. If not, see <http://creativecommons.org/licenses/by/4.0/>.
+Fuel@OPNFV DOCs are licensed under a Creative Commons Attribution 4.0 International License. You should have received a copy of the license along with this. If not, see <http://creativecommons.org/licenses/by/4.0/>.
 
 
 **Contents**
@@ -40,7 +40,10 @@ Fuel@OPNFV DOCs are licensed under a Creative Commons Attribution 4.0 Unported L
 | **Date**           | **Ver.**           | **Author**         | **Comment**        |
 |                    |                    |                    |                    |
 +--------------------+--------------------+--------------------+--------------------+
-| 2015-04-16         | 0.1.0              | Jonas Bjurel       | First draft        |
+| 2015-04-16         | 0.1                | Jonas Bjurel       | First draft        |
+|                    |                    |                    |                    |
++--------------------+--------------------+--------------------+--------------------+
+| 2015-04-23         | 0.2                | Jonas Bjurel       | Minor change       |
 |                    |                    |                    |                    |
 +--------------------+--------------------+--------------------+--------------------+
 
diff --git a/fuel/docs/src/tmp/BUILD/README.architecture b/fuel/docs/src/tmp/BUILD/README.architecture
deleted file mode 100644
index 4629763..0000000
--- a/fuel/docs/src/tmp/BUILD/README.architecture
+++ /dev/null
@@ -1,10 +0,0 @@
-##############################################################################
-# Copyright (c) 2015 Ericsson AB and others.
-# stefan.k.berg@ericsson.com
-# jonas.bjurel@ericsson.com
-# All rights reserved. This program and the accompanying materials
-# are made available under the terms of the Apache License, Version 2.0
-# which accompanies this distribution, and is available at
-# http://www.apache.org/licenses/LICENSE-2.0
-##############################################################################
-
diff --git a/fuel/docs/src/tmp/BUILD/README.build b/fuel/docs/src/tmp/BUILD/README.build
deleted file mode 100644
index b8ce799..0000000
--- a/fuel/docs/src/tmp/BUILD/README.build
+++ /dev/null
@@ -1,98 +0,0 @@
-##############################################################################
-# Copyright (c) 2015 Ericsson AB and others.
-# stefan.k.berg@ericsson.com
-# jonas.bjurel@ericsson.com
-# All rights reserved. This program and the accompanying materials
-# are made available under the terms of the Apache License, Version 2.0
-# which accompanies this distribution, and is available at
-# http://www.apache.org/licenses/LICENSE-2.0
-##############################################################################
-
-How to setup and use the OPNFV/BGS/FUEL build system
-====================================================
-
-1. Build system requirements
-----------------------------
-1.1 Host HW/VM requirements
----------------------------
-- An x86_64 host (real iron or VM) with Ubuntu 14.04 LTS installed
-- ~30 GB available disc
-- 4 GB RAM
-
-1.2 Host SW dependencies
-------------------------
-The host should run Ubuntu 14.04
-On the host, the following packages must be installed:
-- docker - see https://docs.docker.com/installation/ubuntulinux/ for installation notes
-for Ubuntu 14.04. Note: only use the Ubuntu stock distro of Docker (docker.io)
-- git (simply available through apt-get install git)
-- make (simply available through apt-get install make)
-- curl
-
-2 Setting up the Docker build container
-----------------------------------------
-When having installed Docker, add yourself to the docker group:
-usermod -a -G docker <userid>
-
-Also make sure to define rellevant dns servers part of the global dns chain in
-in your /etc/default/docker config file, eg.
-DOCKER_OPTS=" --dns=8.8.8.8 --dns=8.8.8.4"
-
-Then restart docker with "service docker.io restart".:
-
-3. Setting up OPNFV Gerrit in order to being able to clone the code
--------------------------------------------------------------------
-- Start by creating a SSH key, if you don't already have one, create one with ssh-keygen
-
-- Add your generated public key in OPNFV Gerrit -https://gerrit.opnfv.org/
-  (this requires a linuxfoundation account, create one if you do not already have one)
-
-- Select "SSH Public Keys" to the left and then "Add Key" and paste your public key in.
-
-4. Clone the OPNFV code git repository
---------------------------------------
- So now we're coming to the fun part! Let's clone the code repository:
- git clone ssh://<Linux foundation user>@gerrit.opnfv.org:29418/genesis
-
- Change the directory to "fuel-build"
- cd fuel-build/
-
-5. Set up (build) your build environment
-----------------------------------------
-Select the versions of the components you want to build by editing the
-fuel-build/config-spec file. Note if you want to build with OpenDaylight
-SDN controller you need to uncomment the lines starting with odl-main and
-java-main
-
-6. Build your fuel .iso image
------------------------------
-That's it, time to build!
-make [all]
-
-This will:
-- If not allready existing, initialize the docker build environment
-- If not already done, build OpenDaylight from upstream (as defined by fuel-build/
-  config-spec)
-- If not already done, build fuel from upstream (as defined by fuel-build/config-spec)
-- Build the defined additions to fuel (as defined by the structure of this framework)
-- Apply changes and patches to fuel (as defined by the structure of this framework)
-- Reconstruct a fuel .iso image
-
-If the build is successful, you will find the generated ISO file in the release
-subdirectory!
-
-NOTE: the build of the baseline for Fuel and odl are cached, if build results reffering
-to the same versions as specified in fuel-build/config spec has been built before, these
-packages will not be rebuilt. The cache is cleared by "make clean"
-
-7. Install your stack
----------------------
-Please see DOC/INSTALL/README
-
-NOTES and TODO:
----------------
-The build system will for now partly run as sudo
-BUT NOTE, NONE OF THE MAKEFILES OR SCRIPTS SHALL BE EXECUTED WITH
-SUDO/ROOT PRIVILEDGES!
-TODO: Change the scripts so that no root priviledges will be needed
-
diff --git a/fuel/docs/src/tmp/BUILD/README.examples b/fuel/docs/src/tmp/BUILD/README.examples
deleted file mode 100644
index 4629763..0000000
--- a/fuel/docs/src/tmp/BUILD/README.examples
+++ /dev/null
@@ -1,10 +0,0 @@
-##############################################################################
-# Copyright (c) 2015 Ericsson AB and others.
-# stefan.k.berg@ericsson.com
-# jonas.bjurel@ericsson.com
-# All rights reserved. This program and the accompanying materials
-# are made available under the terms of the Apache License, Version 2.0
-# which accompanies this distribution, and is available at
-# http://www.apache.org/licenses/LICENSE-2.0
-##############################################################################
-