diff options
Diffstat (limited to 'docs/build-instruction.rst')
| -rw-r--r-- | docs/build-instruction.rst | 314 |
1 files changed, 314 insertions, 0 deletions
diff --git a/docs/build-instruction.rst b/docs/build-instruction.rst new file mode 100644 index 000000000..b7b13c896 --- /dev/null +++ b/docs/build-instruction.rst @@ -0,0 +1,314 @@ +============================================================================ +OPNFV Build instruction for the Fuel deployment tool +============================================================================ + +.. contents:: Table of Contents + :backlinks: none + +Abstract +======== + +This document describes how to build the Fuel deployment tool for the +B release of OPNFV - the build system, dependencies and required +system resources. + + +License +======= +Brahmaputra release of OPNFV when using Fuel as a deployment tool DOCs (c) by Jonas Bjurel (Ericsson AB) and others. + +Brahmaputra release of OPNFV when using Fuel as a deployment tool DOCs (c) 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/>. + + + +Version history +=============== + ++--------------------+--------------------+--------------------+----------------------+ +| **Date** | **Ver.** | **Author** | **Comment** | +| | | | | ++--------------------+--------------------+--------------------+----------------------+ +| 2015-06-03 | 1.0.0 | Jonas Bjurel | Instruction for | +| | | (Ericsson AB) | the Arno release | ++--------------------+--------------------+--------------------+----------------------+ +| 2015-09-24 | 1.1.0 | Jonas Bjurel | Instruction for | +| | | (Ericsson AB) | the Arno SR1 release | ++--------------------+--------------------+--------------------+----------------------+ +| 2015-10-23 | 1.1.1 | Stefan Berg | Added instruction | +| | | (Ericsson AB) | for proxy builds | ++--------------------+--------------------+--------------------+----------------------+ +| 2015-12-03 | 1.2.0 | Stefan Berg | Added instruction | +| | | (Ericsson AB) | for plugin build | +| | | | selection | ++--------------------+--------------------+--------------------+----------------------+ + +Introduction +============ + +This document describes the build system used to build the Fuel +deployment tool for the Brahmaputra release of 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. + +Requirements +============ + +Minimum Hardware Requirements +----------------------------- + +- An x86_64 host (Bare-metal or VM) with Ubuntu 14.04 LTS installed + +- ~30 GB available disc + +- 4 GB RAM + +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) + +Preparations +------------ + +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, for example: + +<DOCKER_OPTS=" --dns=8.8.8.8 --dns=8.8.8.4"> + +Then restart docker: + +<sudo service docker.io restart> + +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. + +Clone the OPNFV code Git repository with your SSH key +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Now it is time to clone the code repository: + +<git clone ssh://'Linux foundation user'@gerrit.opnfv.org:29418/fuel> + +Now you should have the OPNFV fuel repository with the Fuel +directories stored locally on your build host. + +Check out the Brahmaputra release: +<cd fuel> +<git checkout insert-b-release-tag-here0> + +Clone the OPNFV code Git repository without a SSH key +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You can also opt to clone the code repository without a SSH key: + +<git clone https://gerrit.opnfv.org:29418/gerrit/fuel> + +Make sure to checkout the release tag as described above. + + +Building +======== + +There are two methods available for building Fuel: + +- A low level method using Make + +- An abstracted method using build.sh + + +Support for building behind a http/https/rsync proxy +---------------------------------------------------- + +The build system is able to make use of a web proxy setup if the +http_proxy, https_proxy, no_proxy (if needed) and RSYNC_PROXY or +RSYNC_CONNECT_PROG environment variables have been set before invoking make. + +The proxy setup must permit port 80 (http), 443 (https) and 873 +(rsync). + +Important note about the host Docker daemon settings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Docker daemon on the host must be configured to use the http proxy +for it to be able to pull the base Ubuntu 14.04 image from the Docker +registry before invoking make! In Ubuntu this is done by adding a line +like: + +export http_proxy="http://10.0.0.1:8888/" + +to /etc/default/docker and restarting the Docker daemon. + +Setting proxy environment variables prior to build +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The build system will make use the following environment variables +that needs to be exported to subshells by using export (bash) or +setenv (csh/tcsh). + +| http_proxy (or HTTP_PROXY) +| https_proxy (or HTTP_PROXY) +| no_proxy (or NO_PROXY) +| RSYNC_PROXY +| RSYNC_CONNECT_PROG + +As an example, these are the settings that were put in the user's +.bashrc when verifying the proxy build functionality: + +| export RSYNC_PROXY=10.0.0.1:8888 +| export http_proxy=http://10.0.0.1:8888 +| export https_proxy=http://10.0.0.1:8888 +| export no_proxy=localhost,127.0.0.1,.consultron.com,.sock + +Using a ssh proxy for the rsync connection +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If the proxy setup is not allowing the rsync protocol, an alternative +solution is to use a SSH tunnel to a machine capable of accessing the +outbound port 873. Set the RSYNC_CONNECT_PROG according to the rsync +manual page (for example to "ssh <username>@<hostname> nc %H 873") to enable +this. Also note that netcat needs to be installed on the remote +system! + +Make sure that the ssh command also refers to the user on the remote +system, as the command itself will be run from the Docker build container +as the root user (but with the invoking user's SSH keys). + +Disabling the Ubuntu repo cache if rsync is not allowed +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +During the build phase, a local Ubuntu package repository is fetched +from upstream in order to be added to the OPNFV Fuel ISO and for parts +of this process rsync is used. + +If neither of the two available methods for proxying rsync are +available, the last resort is to turn off the caching of the Ubuntu +packages in the build system. This is done by removing the +"f_repobuild" from SUBDIRS in the beginning of +the fuel/build/f_isoroot/Makefile. + +Note! Doing this will require the Fuel master node to have Internet +access when installing the ISO artifact built as no Ubuntu package +cache will be on the ISO! + +Configure your build environment +------------------------------------- + +** Configuring the build environment should not be performed if building standard Brahmaputra release ** + +Select the versions of the components you want to build by editing the fuel/build/config.mk file. + +Non official build: Selecting which plugins to build +---------------------------------------------------- +In order to cut the build time for unofficial builds (made by an +individual developer locally), the selection if which Fuel plugins to +build (if any) can be done by environment variable +"BUILD_FUEL_PLUGINS" prior to building. + +Only the plugin targets from fuel/build/f_isoroot/Makefile that are +specified in the environment variable will then be built. In order to +completely disable the building of plugins, the environment variable +is set to " ". When using this functionality, the resulting iso file +will be prepended with the prefix "unofficial-" to clearly indiciate +that this is not a full build. + +This method of plugin selection is not meant to be used from within +Gerrit! + +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 already 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! + +Abstracted build method using build.sh +====================================== +The abstracted build method uses 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>. + +Artifacts +========= + +The artifacts produced are: + +- <OPNFV_XXXX.iso> - Which represents the bootable Fuel image, XXXX is + replaced with the build identity provided to the build system + +- <OPNFV_XXXX.iso.txt> - Which holds version metadata. + +References +========== +- + +:Authors: Jonas Bjurel (Ericsson), Stefan Berg (Ericsson) +:Version: x.x.x + +**Documentation tracking** + +Revision: _sha1_ + +Build date: _date_ |