packaging/docker/README.md

   1 What is Docker
   2 ==============
   3 Docker, provided by [docker.io](http://docker.io), and available in most Linux distributions as well as available on MacOS and Windows, is an open-source project to easily create lightweight, portable, self-sufficient containers from any application. The same container that a developer builds and tests on a laptop can run at scale, in production, on VMs, bare metal, OpenStack clusters, public clouds and more.
   4
   5 _For more information on docker please read [docker.io's documentation](http://docker.io)._
   6
   7 <a name="sudo"></a>The sudo command and the docker Group
   8 =====================================
   9 (reprinted from [docker.io's basic documentation](http://docs.docker.io/en/latest/use/basics/)):
  10
  11 The docker daemon always runs as the root user, and since Docker version 0.5.2, the docker daemon binds to a Unix socket instead of a TCP port. By default that Unix socket is owned by the user root, and so, by default, you can access it with sudo.
  12
  13 Starting in version 0.5.3, if you (or your Docker installer) create a Unix group called docker and add users to it, then the docker daemon will make the ownership of the Unix socket read/writable by the docker group when the daemon starts. The docker daemon must always run as the root user, but if you run the docker client as a user in the docker group then you don’t need to add sudo to all the client commands.
  14
  15 <a name="images"></a>OpenDaylight Docker Images
  16 ==========================
  17 The `Dockerfile`s in these directories can be used to construct a docker image for an OpenDaylight SDN controller. These Dockerfiles rely on the presense of an OpenDaylight distribution in the sub-directory `target/dist`. The distribution should be a `ZIP` file as generated by an OpenDaylight source build or as downloaded from the [OpenDaylight Nexus server](https://nexus.opendaylight.org/content/repositories/opendaylight.snapshot/org/opendaylight/integration).
  18
  19 <a name="prebuilt"></a>Pre-built Image
  20 ===============
  21 If you would like to use the OpenDaylight SDN controller as a docker image, but do not wish to build the image yourself. There are public images available via the public docker respository. You can find the images by issuing a docker search command looking for __opendaylight__ i.e.
  22
  23     $ docker search opendaylight
  24     Found 3 results matching your query ("opendaylight")
  25     NAME                             DESCRIPTION
  26     opendaylight/base                The base OpenDaylight SDN controlelr
  27     opendaylight/serviceprovider     The service provider version of the OpenDaylight SDN controller
  28     opendaylight/virtualization      The virtualization version of the OpenDaylight SDN controller
  29
  30 Each of these images have version tags that allow the sepecification of the version via the version name. `latest` is also a support tag to identify the latest offical release. For the first release of OpenDaylight, the version tag is "hydrogen".
  31
  32 <a name="building"></a>Build Image
  33 ===========
  34 If you would like to build the image manually then this can be done by performing a `mvn install` command from the top of the OpenDaylight docker module `integration/packaging/docker` or in the sub-directory for the edition in which you are interested, i.e., `integration/packaging/docker/base`. This will retrieve the latest artifacts from your local maven repository and copy them to the `target/dist` sub-directory in the associated edition directories in preparation to build the docker images.
  35
  36 Once the distribution `ZIP` file is in the `target/dist` sub-directory the image can be built from the edition sub-directories using with the following command:
  37
  38     docker build -t="<respository>/<name>:<tag>" -rm .
  39
  40 When issuing this command you can replace the the `<repository>/<name>:<tag>` values with any name you would like, or none if you wish to only using the generated image identifiers. As an exmaple:
  41
  42     docker build -t="joeuser/opendaylight:mytag" -rm .
  43
  44 More information about the docker build command can be found at [docker.io's documenation page](http://docs.docker.io/en/latest/commandline/cli/#cli-build).
  45
  46 <a name="release"></a>Release Images
  47 ==============
  48 In the `release` sub-directory, additional Dockerfiles are located. These Dockerfiles can be used to build a docker image by directly downloading the distribution files from the OpenDaylight Nexus repository. These are the files that are used to build the official images that are published to the [docker.io public repository](index.docker.io).
  49
  50 The following command can be used to build images using these files:
  51
  52     docker build -rm - < Dockerfile.<edition>
  53
  54 <a name="use"></a>Using the Image
  55 ===============
  56 The OpenDaylight docker image is meant to be used to start an instance of the OpenDaylight SDN controller and that process will be invoked when the docker image is __run__. Any command line options you append to the `docker run` command will be passed on to the the OpenDaylight `run.sh` startup script. In its simpliest form you can invoke an instance of the Opendaylight controller using the command:
  57
  58     docker run -d <image-identifier>
  59
  60 Where `<image-identifier>` can be one of the pre-build image references, i.e. `opendaylight/base:hydrogen`, or it can reference the docker image you may have created using the `Dockerfile` and the `docker build` command.
  61
  62 Additional information and options for _running_ a docker image can be found at [docker.io's run documentation](http://docs.docker.io/en/latest/commandline/cli/#run).
  63
  64 Ports
  65 -----
  66 The OpenDaylight controller image will expose the following ports from the container to the host system:
  67
  68 + 1088 - JMX access
  69 + 1830 - Netconf use
  70 + 2400 - OSGi console
  71 + 4342 - Lisp Flow Mapping (for Service Provider Edition only)
  72 + 5666 - ODL Internal clustering RPC
  73 + 6633 - OpenFlow use
  74 + 7800 - ODL Clustering
  75 + 8000 - Java debug access
  76 + 8080 - OpenDaylight web portal
  77 + 8383 - Netconf use
  78 + 12001 - ODL Clustering
  79
  80 By default these ports will be mapped to random ports on the host system (i.e. the system on which the `docker run` command is invoked). The mappings can be discovered using the `docker ps` command. To understand how to enable docker container instances to communicate without having to _hard wire_ the port information see [docker.io's documentation on linking](http://docs.docker.io/en/latest/use/working_with_links_names/).
  81
  82 If you wish to map these ports to specific port numbers on the host system, this can be accomplished as command line options to the `docker run` command using the _port map_ option specified using the `-p` option. The syntax for this option is documented in [docker.io's run documentation](http://docs.docker.io/en/latest/commandline/cli/#run), but is essentially `-p <host-port>:<container-port>`.
  83
  84 <a name="clustering"></a>Clustering
  85 ===========
  86 OpenDaylight supports the concept of [clustering](https://wiki.opendaylight.org/view/OpenDaylight_Controller:Programmer_Guide:Clustering) using a command line option [`-Dsupernodes`](https://wiki.opendaylight.org/view/OpenDaylight_Controller:Clustering:HowTo) to support high availability.
  87
  88 The docker images can be used to set up a cluster on a single docker server (host) using the [docker naming and linking capability](http://blog.docker.io/2013/10/docker-0-6-5-links-container-naming-advanced-port-redirects-host-integration/) along with some modifications that were made to the OpenDaylight's processing of the `supernodes` host specifications.
  89
  90 _NOTE: The cluster configuraiton setup described in this document does not work for containers that are running on separate hosts. Supporting clustering using docker images across hosts is an advanced topic that relies on setting up virtual networks between the containers and is beyond the scope of this introduction._
  91
  92 To support docker based clustering the syntax of the `supernodes` parameter has been extended. The important changes are:
  93
  94 + `+self` - interpreted as a reference to the local host's address (not 127.0.0.1) and will be resolved to an IP address through the environment variable `HOSTNAME`.
  95 + `+<name>` - interpreted as a reference to another container, `<name>`, and will be resolved using the environment variables defined by docker when the `-link` command line option is used
  96
  97 It is important to note that these extensions will only be used if OpenDaylight determines that it is running inside a container. This is determined by the value of the environment variable `container` being set to `lxc`.
  98
  99 All values not prefixed by a `+` will be interpreted normally.
 100
 101 Below is an example of starting up a three node cluster using this syntax:
 102
 103     $ docker run -d -name node1 opendaylight/base:hydrogen -Dsupernodes=+self
 104     a8435cc23e13cb4e04c3c9788789e7e831af61c735d14a33025b3dd6c76e2938
 105     $ docker run -d -name node2 -link node1:n1 d44fd77ebbdf -Dsupernodes=+self:+n1
 106     fa0b37dfd216291e36fd645a345751a1a6079123c99d75326a5775dce8414a93
 107     $ docker run -d -name node3 -link node1:n1 d44fd77ebbdf -Dsupernodes=+self:+n1
 108     9ad6874aa85cad29736030239baf836f46ceb0c242baf873ab455674040d96b1
 109
 110 The cluster can be verified through the OpenDaylight user interface. This can be accomplished by first determining the IP address of one of the nodes:
 111
 112     $ docker inspect -format='{{.NetworkSettings.IPAddress}}' node1
 113     172.17.0.46
 114
 115 After determining the IP address you can view the web interface by typing `http://172.17.0.46:8080` in the browser address bar, authenticating with the default user name and password (`admin/admin`), and then viewing the cluster information by selecting `Cluster` from the right hand drop down menu. A popup window should be displayed that shows all the nodes in the cluster with the master marked with a `C` and the node to which you are currently connected marked with a `*` (astericks).
 116