deb/README.markdown

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