packages/deb/README.markdown

   1 # OpenDaylight Debian Packages
   2
   3 Logic for building OpenDaylight's upstream Debian packages.
   4
   5 #### Table of Contents
   6
   7 1. [Overview](#overview)
   8 2. [Vagrant Build Environment](#vagrant-build-environment)
   9 3. [Docker provider](#docker-provider)
  10 4. [Building Debs](#building-debs)
  11 5. [Defining New Debs](#defining-new-debs)
  12 6. [Deb Build Variables](#deb-build-variables)
  13 7. [Using Debs](#using-debs)
  14 8. [Installing](#installing)
  15 9. [Uninstalling](#uninstalling)
  16 10. [Using systemd](#using-systemd)
  17 11. [Starting](#starting)
  18 12. [Stopping](#stopping)
  19 13. [Karaf shell](#karaf-)
  20 14. [Using OpenSUSE Build Service](#using-obs)
  21
  22 ## Overview
  23
  24 TODO: Overview of Debian pkg builds, plans
  25
  26 ## Vagrant Build Environment
  27
  28 The included Vagrantfile defines a consistent, known-working and easily
  29 shared environment. It supports both VM and container-based providers.
  30
  31 ```
  32 [~/packaging/deb]$ vagrant status
  33 Current machine states:
  34
  35 default                   not created (libvirt)
  36 [~/packaging/deb]$ vagrant up
  37 [~/packaging/deb]$ vagrant ssh
  38 [vagrant@localhost ~]$ ls /vagrant/
  39 opendaylight  README.markdown  Vagrantfile
  40 ```
  41
  42 ### Docker provider
  43
  44 The Vagrantfile defines a Docker provider, enabling easy access to build.py
  45 in a container. The general command format is:
  46
  47 ```
  48 $ vagrant docker-run -- <flags to build.py>
  49 ```
  50
  51 To pass 5.0 (Boron) as the version to build:
  52
  53 ```
  54 $ vagrant docker-run -- -v 5 0
  55 ```
  56
  57 Dockerfile can be also used directly to build container image:
  58
  59 ```
  60 $ docker build -t "odl_deb" .
  61 $ docker run -v $(pwd):/build odl_deb -v 5 0
  62 ```
  63
  64 ## Building Debs
  65
  66 The `build.py` helper script is used for building OpenDaylight .debs.
  67
  68 The `build.py` helper script can build a set of .debs based on provided
  69 version arguments.
  70
  71 ```
  72 [vagrant@localhost ~]$ /vagrant/build.py -h
  73 usage: build.py [-h] [-v [major minor patch deb [major minor patch deb ...]]]
  74 ....
  75
  76 optional arguments:
  77   -h, --help            show this help message and exit
  78
  79 Existing build:
  80   -v [major minor patch deb [major minor patch deb ...]], --version [major minor patch deb [major minor patch deb ...]]
  81                     Deb version(s) to build
  82 ....
  83 ```
  84
  85 The `-v`/`--version` flag accepts a version number. Any build that matches
  86 the portions provided will be built. If more than one build matches the
  87 portions provided, all matching builds will be executed.
  88
  89 For example, `build.py -v 3` would execute the builds that match the regex
  90 `3.*.*-*`. OpenDaylight 3.0.0-1 and 3.1.0-1, for example.
  91
  92 To only build a single debian package, provide enough version info to make
  93 the match unique. For example, `build.py -v 2 4 0 1` could only match one
  94 definition (Helium SR4, 2.4.0-1).
  95
  96 The `build.py` script uses `templates/build_debianfiles.py` to generate debian files for
  97 ODL .deb packages using JinJa2 templates and dynamic build data provided in `build_vars.yaml`.
  98
  99 ## Defining New Debs
 100
 101 The dynamic aspects of a build, such as ODL and Deb version info, have all
 102 been extracted to a single YAML configuration file. For most Deb updates,
 103 only that configuration file should need to be updated by humans.
 104
 105 The variables available for configuration are documented below. A build
 106 definition should define all supported variables.
 107
 108 ### Deb Build Variables
 109
 110 #### `version_major`
 111
 112 The OpenDaylight major (element) version number of the release to build.
 113
 114 For example, Hydrogen is 1.x.x, Helium is 2.x.x, Lithium is 3.x.x and so on
 115 down the periodic table.
 116
 117 #### `version_minor`
 118
 119 The OpenDaylight minor (SR) version number of the release to build.
 120
 121 #### `version_patch`
 122
 123 The OpenDaylight patch version of the release to build.
 124
 125 #### `pkg_version`
 126
 127 Debian revision for the given ODL major.minor.patch version.
 128
 129 In addition to OpenDaylight's version, .debs themselves have versions. These
 130 are called "debian revisions". For a given OpenDaylight major.minor.patch
 131 version, there will be one or more major.minor.patch-pkg_version .debs.
 132
 133 #### `sysd_commit`
 134
 135 Version of ODL systemd unitfile to download and package in ODL .deb.
 136
 137 The version of OpenDaylight's systemd unitfile, specified by the
 138 git commit hash, is downloaded from the [Int/Pack repo][16] and
 139 consumed by OpenDaylight's Deb builds.
 140
 141 #### `codename`
 142
 143 Elemental codename for the ODL release, including SR if applicable.
 144
 145 Examples include "Helium-SR4", "Lithium" and "Lithium-SR1".
 146
 147 #### `download_url`
 148
 149 The ODL Deb repackages the tarball build artifact produced by ODL's
 150 autorelease build. This is the URL to the tarball ODL build to repackage
 151 into a Debian package.
 152
 153 #### `java_version`
 154
 155 Java dependency for specific ODL builds
 156
 157 #### `changelog`
 158
 159 Entry in the debian/changelog file for specific .deb.
 160
 161 A debian/changelog file for specialized ODL builds is generated using these entries.
 162
 163 The changelog entry must follow a specific format. It's best to follow the
 164 examples provided by existing build definitions closely.
 165
 166 ## Using Debs
 167
 168 The familiar Deb-related commands apply to OpenDaylight's Debs.
 169
 170 ### Installing
 171
 172 To install a local OpenDaylight .deb package and resolve its dependencies, use `sudo gdebi <path to ODL .deb>`
 173
 174 Here's a walk-through of an install and the resulting system changes.
 175
 176 ```
 177 # Note that there's nothing in /opt before the install
 178 [vagrant@localhost vagrant]$ ls /opt/
 179 # Note that there are no ODL systemd files before the install
 180 [vagrant@localhost vagrant]$ ls /lib/systemd/system | grep -i opendaylight
 181 # Install an ODL .deb package
 182 [vagrant@localhost vagrant]$ sudo gdebi opendaylight/opendaylight_0.4.2-Beryllium-SR2-0_amd64.deb
 183 # Note that ODL is now installed in /opt
 184 [vagrant@localhost vagrant]$ ls /opt/
 185 opendaylight
 186 # Note that there's now a systemd .service file for ODL
 187 [vagrant@localhost vagrant]$ ls /lib/systemd/system | grep -i opendaylight
 188 opendaylight.service
 189 ```
 190
 191 ### Uninstalling
 192
 193 To uninstall a local OpenDaylight .deb package, use sudo apt-get remove opendaylight
 194
 195 Here's a walk-through of the uninstall and the resulting system changes.
 196
 197 ```
 198 # Note that ODL is installed in /opt/
 199 [vagrant@localhost vagrant]$ ls /opt/
 200 opendaylight
 201 # Note that there's a systemd .service file for ODL
 202 [vagrant@localhost vagrant]$ ls /lib/systemd/system | grep -i opendaylight
 203 opendaylight.service
 204 # Uninstall the ODL .deb package
 205 [vagrant@localhost vagrant]$ sudo apt-get remove opendaylight
 206 # Note that ODL user data has not been removed from /opt/
 207 [vagrant@localhost vagrant]$ ls /opt/opendaylight/
 208 data  instances
 209 # Uninstall the ODL .deb package and delete user data and configuration
 210 [vagrant@localhost vagrant]$ sudo apt-get purge opendaylight
 211 # Note that ODL has been completely removed from /opt/
 212 [vagrant@localhost vagrant]$ ls /opt/
 213 # Note that the ODL systemd .service file has been removed
 214 [vagrant@localhost vagrant]$ ls /lib/systemd/system | grep -i opendaylight
 215 ```
 216
 217 ## Using systemd
 218
 219 OpenDaylight's debs ship with systemd support.
 220
 221 ### Starting
 222
 223 ```
 224 [vagrant@localhost ~]$ sudo systemctl start opendaylight
 225 [vagrant@localhost ~]$ sudo systemctl status opendaylight
 226 ● opendaylight.service - OpenDaylight SDN Controller
 227    Loaded: loaded (/lib/systemd/system/opendaylight.service; enabled)
 228    Active: active (running) since Tue 2016-08-02 17:33:29 GMT; 2min 7s ago
 229      Docs: https://wiki.opendaylight.org/view/Main_Page
 230            http://www.opendaylight.org/
 231   Process: 1181 ExecStart=/opt/opendaylight/bin/start (code=exited, status=0/SUCCESS)
 232  Main PID: 1188 (java)
 233    CGroup: /system.slice/opendaylight.service
 234            └─1188 /usr/bin/java -Djava.security.properties=/opt/opendaylight/etc/odl.java.security -server -Xms128M -Xmx2048m -XX:+UnlockDiagnosticVMOptions -XX:+Unsy...
 235 ```
 236
 237 ### Stopping
 238
 239 ```
 240 [vagrant@localhost ~]$ sudo systemctl stop opendaylight
 241 [vagrant@localhost ~]$ sudo systemctl status OpenDaylight
 242 ● opendaylight.service - OpenDaylight SDN Controller
 243    Loaded: loaded (/lib/systemd/system/opendaylight.service; enabled)
 244    Active: inactive (dead) since Tue 2016-08-02 17:39:02 GMT; 10s ago
 245      Docs: https://wiki.opendaylight.org/view/Main_Page
 246            http://www.opendaylight.org/
 247   Process: 1181 ExecStart=/opt/opendaylight/bin/start (code=exited, status=0/SUCCESS)
 248  Main PID: 1188 (code=exited, status=143)
 249 ```
 250
 251 ## Karaf shell
 252
 253 A few seconds after OpenDaylight is started, its Karaf shell will be accessible.
 254
 255 You can connect by SSHing into ODL's karaf port and logging in (karaf/karaf).
 256
 257 ```
 258 [vagrant@localhost ~]$ ssh -p 8101 karaf@localhost
 259 Password authentication
 260 Password:
 261
 262     ________                       ________                .__  .__       .__     __
 263     \_____  \ ______   ____   ____ \______ \ _____  ___.__.|  | |__| ____ |  |___/  |
 264      /   |   \\____ \_/ __ \ /    \ |    |  \\__  \<   |  ||  | |  |/ ___\|  |  \   __\
 265     /    |    \  |_> >  ___/|   |  \|    `   \/ __ \\___  ||  |_|  / /_/  >   Y  \  |
 266     \_______  /   __/ \___  >___|  /_______  (____  / ____||____/__\___  /|___|  /__|
 267             \/|__|        \/     \/        \/     \/\/            /_____/      \/
 268
 269
 270 Hit '<tab>' for a list of available commands
 271 and '[cmd] --help' for help on a specific command.
 272 Hit '<ctrl-d>' or type 'system:shutdown' or 'logout' to shutdown OpenDaylight.
 273
 274 opendaylight-user@root>
 275 ```
 276
 277 ## Using OpenSUSE Build Service
 278
 279 After building Debs as described above, we use the [OpenSUSE Build Service][1] to build and
 280 host Debs for consumption. The Boron .deb package for Debian/Ubuntu, can be installed by
 281 following the instructions given [here][2].
 282
 283 [1]: https://build.opensuse.org/
 284
 285 [2]: http://software.opensuse.org/download.html?project=home%3Aakshitajha&package=opendaylight