From 2d339a2ac39fbab78f81b0dc0054882c2b92509b Mon Sep 17 00:00:00 2001 From: Jonas Bjurel Date: Thu, 16 Apr 2015 22:41:56 +0200 Subject: Fuel documentation ready for review JIRA: Change-Id: Icaa2decbd82a3a857141a127d9f536474f478901 Signed-off-by: Jonas Bjurel --- fuel/docs/src/build-instructions.rst | 177 ++++++++++++++++++++++++++++ fuel/docs/src/installation-instructions.rst | 19 +-- fuel/docs/src/release-notes.rst | 9 +- fuel/docs/src/tmp/BUILD/README.architecture | 10 -- fuel/docs/src/tmp/BUILD/README.build | 98 --------------- fuel/docs/src/tmp/BUILD/README.examples | 10 -- 6 files changed, 194 insertions(+), 129 deletions(-) create mode 100644 fuel/docs/src/build-instructions.rst delete mode 100644 fuel/docs/src/tmp/BUILD/README.architecture delete mode 100644 fuel/docs/src/tmp/BUILD/README.build delete mode 100644 fuel/docs/src/tmp/BUILD/README.examples (limited to 'fuel/docs/src') 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 , 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 . + + +**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: + + + +Also make sure to define relevant DNS servers part of the global dns chain in +in your configuration file, eg. + + + +Then restart docker: + + + +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 + (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: + + + +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 invoke + +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 subdirectory! + +4.3 Abstracted build method using build.sh +=========================================== +The abstracted build method useses the 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 . + +5 Artifacts +============= + +The artifacts produced are: + +- - Which represents the bootable Fuel@OPNFV image, XXXX is replaced with the build identity provided to the build system + +- - 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 . +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 . **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 . - + - Check the three servers you want to be installed as Controllesr in pane . - Click . - + - Check . - + - Check nodes to be installed as Compute nodes in pane Assign Role. - Click . @@ -327,7 +330,7 @@ This section describes the installation of the Fuel@OPNFV installation server (F - Check Select to select all nodes with Control, Telemetry . MongoDB and Compute node roles. - Click - + - Screen Configure interfaces on number of 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 . +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 . **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 - -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://@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 -############################################################################## - -- cgit 1.2.3-korg