docs/development/overview/build/build.instruction.rst

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