docs/build-instruction.rst

   1 ============================================================================
   2 OPNFV Build instruction for the Fuel deployment tool
   3 ============================================================================
   4
   5 .. contents:: Table of Contents
   6    :backlinks: none
   7
   8 Abstract
   9 ========
  10
  11 This document describes how to build the Fuel deployment tool for the
  12 B release of OPNFV - the build system, dependencies and required
  13 system resources.
  14
  15
  16 License
  17 =======
  18 Brahmaputra release of OPNFV when using Fuel as a deployment tool DOCs (c) by Jonas Bjurel (Ericsson AB) and others.
  19
  20 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/>.
  21
  22
  23
  24 Version history
  25 ===============
  26
  27 +--------------------+--------------------+--------------------+----------------------+
  28 | **Date**           | **Ver.**           | **Author**         | **Comment**          |
  29 |                    |                    |                    |                      |
  30 +--------------------+--------------------+--------------------+----------------------+
  31 | 2015-06-03         | 1.0.0              | Jonas Bjurel       | Instruction for      |
  32 |                    |                    | (Ericsson AB)      | the Arno release     |
  33 +--------------------+--------------------+--------------------+----------------------+
  34 | 2015-09-24         | 1.1.0              | Jonas Bjurel       | Instruction for      |
  35 |                    |                    | (Ericsson AB)      | the Arno SR1 release |
  36 +--------------------+--------------------+--------------------+----------------------+
  37 | 2015-10-23         | 1.1.1              | Stefan Berg        | Added instruction    |
  38 |                    |                    | (Ericsson AB)      | for proxy builds     |
  39 +--------------------+--------------------+--------------------+----------------------+
  40 | 2015-12-03         | 1.2.0              | Stefan Berg        | Added instruction    |
  41 |                    |                    | (Ericsson AB)      | for plugin build     |
  42 |                    |                    |                    | selection            |
  43 +--------------------+--------------------+--------------------+----------------------+
  44
  45 Introduction
  46 ============
  47
  48 This document describes the build system used to build the Fuel
  49 deployment tool for the Brahmaputra release of OPNFV, required
  50 dependencies and minimum requirements on the host to be used for the
  51 buildsystem.
  52
  53 The Fuel build system is desigened around Docker containers such that
  54 dependencies outside of the build system can be kept to a minimum. It
  55 also shields the host from any potential dangerous operations
  56 performed by the build system.
  57
  58 The audience of this document is assumed to have good knowledge in
  59 network and Unix/Linux administration.
  60
  61 Requirements
  62 ============
  63
  64 Minimum Hardware Requirements
  65 -----------------------------
  66
  67 - An x86_64 host (Bare-metal or VM) with Ubuntu 14.04 LTS installed
  68
  69 - ~30 GB available disc
  70
  71 - 4 GB RAM
  72
  73 Minimum Software Requirements
  74 -----------------------------
  75
  76 The build host should run Ubuntu 14.04 operating system.
  77
  78 On the host, the following packages must be installed:
  79
  80 - docker - see https://docs.docker.com/installation/ubuntulinux/ for
  81   installation notes for Ubuntu 14.04. Note: only use the Ubuntu stock
  82   distro of Docker (docker.io)
  83
  84 - git (simply available through sudo apt-get install git)
  85
  86 - make (simply available through sudo apt-get install make)
  87
  88 - curl (simply available through sudo apt-get install curl)
  89
  90 Preparations
  91 ------------
  92
  93 Setting up the Docker build container
  94 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  95 After having installed Docker, add yourself to the docker group:
  96
  97 <usermod -a -G docker [userid]>
  98
  99 Also make sure to define relevant DNS servers part of the global dns chain in
 100 in your </etc/default/docker> configuration file, for example:
 101
 102 <DOCKER_OPTS=" --dns=8.8.8.8 --dns=8.8.8.4">
 103
 104 Then restart docker:
 105
 106 <sudo service docker.io restart>
 107
 108 Setting up OPNFV Gerrit in order to being able to clone the code
 109 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 110 - Start setting up OPNFV gerrit by creating a SSH key (unless you
 111   don't already have one), create one with ssh-keygen
 112
 113 - Add your generated public key in OPNFV Gerrit <https://gerrit.opnfv.org/>
 114   (this requires a linuxfoundation account, create one if you do not
 115   already have one)
 116
 117 - Select "SSH Public Keys" to the left and then "Add Key" and paste
 118   your public key in.
 119
 120 Clone the OPNFV code Git repository with your SSH key
 121 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 122 Now it is time to clone the code repository:
 123
 124 <git clone ssh://'Linux foundation user'@gerrit.opnfv.org:29418/fuel>
 125
 126 Now you should have the OPNFV fuel repository with the Fuel
 127 directories stored locally on your build host.
 128
 129 Check out the Brahmaputra release:
 130 <cd fuel>
 131 <git checkout insert-b-release-tag-here0>
 132
 133 Clone the OPNFV code Git repository without a SSH key
 134 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 135 You can also opt to clone the code repository without a SSH key:
 136
 137 <git clone https://gerrit.opnfv.org:29418/gerrit/fuel>
 138
 139 Make sure to checkout the release tag as described above.
 140
 141
 142 Building
 143 ========
 144
 145 There are two methods available for building Fuel:
 146
 147 - A low level method using Make
 148
 149 - An abstracted method using build.sh
 150
 151
 152 Support for building behind a http/https/rsync proxy
 153 ----------------------------------------------------
 154
 155 The build system is able to make use of a web proxy setup if the
 156 http_proxy, https_proxy, no_proxy (if needed) and RSYNC_PROXY or
 157 RSYNC_CONNECT_PROG environment variables have been set before invoking make.
 158
 159 The proxy setup must permit port 80 (http), 443 (https) and 873
 160 (rsync).
 161
 162 Important note about the host Docker daemon settings
 163 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 164
 165 The Docker daemon on the host must be configured to use the http proxy
 166 for it to be able to pull the base Ubuntu 14.04 image from the Docker
 167 registry before invoking make! In Ubuntu this is done by adding a line
 168 like:
 169
 170 export http_proxy="http://10.0.0.1:8888/"
 171
 172 to /etc/default/docker and restarting the Docker daemon.
 173
 174 Setting proxy environment variables prior to build
 175 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 176
 177 The build system will make use the following environment variables
 178 that needs to be exported to subshells by using export (bash) or
 179 setenv (csh/tcsh).
 180
 181 | http_proxy (or HTTP_PROXY)
 182 | https_proxy (or HTTP_PROXY)
 183 | no_proxy (or NO_PROXY)
 184 | RSYNC_PROXY
 185 | RSYNC_CONNECT_PROG
 186
 187 As an example, these are the settings that were put in the user's
 188 .bashrc when verifying the proxy build functionality:
 189
 190 | export RSYNC_PROXY=10.0.0.1:8888
 191 | export http_proxy=http://10.0.0.1:8888
 192 | export https_proxy=http://10.0.0.1:8888
 193 | export no_proxy=localhost,127.0.0.1,.consultron.com,.sock
 194
 195 Using a ssh proxy for the rsync connection
 196 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 197
 198 If the proxy setup is not allowing the rsync protocol, an alternative
 199 solution is to use a SSH tunnel to a machine capable of accessing the
 200 outbound port 873. Set the RSYNC_CONNECT_PROG according to the rsync
 201 manual page (for example to "ssh <username>@<hostname> nc %H 873") to enable
 202 this. Also note that netcat needs to be installed on the remote
 203 system!
 204
 205 Make sure that the ssh command also refers to the user on the remote
 206 system, as the command itself will be run from the Docker build container
 207 as the root user (but with the invoking user's SSH keys).
 208
 209 Disabling the Ubuntu repo cache if rsync is not allowed
 210 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 211
 212 During the build phase, a local Ubuntu package repository is fetched
 213 from upstream in order to be added to the OPNFV Fuel ISO and for parts
 214 of this process rsync is used.
 215
 216 If neither of the two available methods for proxying rsync are
 217 available, the last resort is to turn off the caching of the Ubuntu
 218 packages in the build system. This is done by removing the
 219 "f_repobuild" from SUBDIRS in the beginning of
 220 the fuel/build/f_isoroot/Makefile.
 221
 222 Note! Doing this will require the Fuel master node to have Internet
 223 access when installing the ISO artifact built as no Ubuntu package
 224 cache will be on the ISO!
 225
 226 Configure your build environment
 227 -------------------------------------
 228
 229 ** Configuring the build environment should not be performed if building standard Brahmaputra release **
 230
 231 Select the versions of the components you want to build by editing the fuel/build/config.mk file.
 232
 233 Non official build: Selecting which plugins to build
 234 ----------------------------------------------------
 235 In order to cut the build time for unofficial builds (made by an
 236 individual developer locally), the selection if which Fuel plugins to
 237 build (if any) can be done by environment variable
 238 "BUILD_FUEL_PLUGINS" prior to building.
 239
 240 Only the plugin targets from fuel/build/f_isoroot/Makefile that are
 241 specified in the environment variable will then be built. In order to
 242 completely disable the building of plugins, the environment variable
 243 is set to " ". When using this functionality, the resulting iso file
 244 will be prepended with the prefix "unofficial-" to clearly indiciate
 245 that this is not a full build.
 246
 247 This method of plugin selection is not meant to be used from within
 248 Gerrit!
 249
 250 Low level build method using make
 251 ---------------------------------
 252 The low level method is based on Make:
 253
 254 From the <fuel/build> directory, invoke <make [target]>
 255
 256 Following targets exist:
 257
 258 - none/all -  this will:
 259
 260   - If not already existing, initialize the docker build environment
 261
 262   - If not already done, build OpenDaylight from upstream (as defined
 263     by fuel-build config-spec)
 264
 265   - If not already done, build fuel from upstream (as defined by
 266     fuel-build/config-spec)
 267
 268   - Build the defined additions to fuel (as defined by the structure
 269     of this framework)
 270
 271   - Apply changes and patches to fuel (as defined by the structure of
 272     this framework)
 273
 274   - Reconstruct a fuel .iso image
 275
 276 - clean - this will remove all artifacts from earlier builds.
 277
 278 If the build is successful, you will find the generated ISO file in
 279 the <fuel/build/release> subdirectory!
 280
 281 Abstracted build method using build.sh
 282 ======================================
 283 The abstracted build method uses the <fuel/ci/build.sh> script which
 284 allows you to:
 285
 286 - Create and use a build cache - significantly speeding up the
 287   buildtime if upstream repositories have not changed.
 288
 289 - push/pull cache and artifacts to an arbitrary URI (http(s):, file:, ftp:)
 290
 291 For more info type <fuel/ci/build.sh -h>.
 292
 293 Artifacts
 294 =========
 295
 296 The artifacts produced are:
 297
 298 - <OPNFV_XXXX.iso> - Which represents the bootable Fuel image, XXXX is
 299   replaced with the build identity provided to the build system
 300
 301 - <OPNFV_XXXX.iso.txt> - Which holds version metadata.
 302
 303 References
 304 ==========
 305 -
 306
 307 :Authors: Jonas Bjurel (Ericsson), Stefan Berg (Ericsson)
 308 :Version: x.x.x
 309
 310 **Documentation tracking**
 311
 312 Revision:  _sha1_
 313
 314 Build date:  _date_