_For more information on docker please read [docker.io's documentation](http://docker.io)._
-The sudo command and the docker Group
+<a name="sudo"></a>The sudo command and the docker Group
=====================================
(reprinted from [docker.io's basic documentation](http://docs.docker.io/en/latest/use/basics/)):
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.
-OpenDaylight Docker Images
+<a name="images"></a>OpenDaylight Docker Images
==========================
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).
-Pre-built Image
+<a name="prebuilt"></a>Pre-built Image
===============
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.
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".
-Build Image
+<a name="building"></a>Build Image
===========
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.
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).
-Release Images
+<a name="release"></a>Release Images
==============
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).
docker build -rm - < Dockerfile.<edition>
-Using the Image
+<a name="use"></a>Using the Image
===============
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:
+ 1088 - JMX access
+ 1830 - Netconf use
+ 2400 - OSGi console
++ 4342 - Lisp Flow Mapping (for Service Provider Edition only)
++ 5666 - ODL Internal clustering RPC
+ 6633 - OpenFlow use
++ 7800 - ODL Clustering
+ 8000 - Java debug access
+ 8080 - OpenDaylight web portal
+ 8383 - Netconf use
++ 12001 - ODL Clustering
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/).
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>`.
+<a name="clustering"></a>Clustering
+===========
+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.
+
+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.
+
+_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._
+
+To support docker based clustering the syntax of the `supernodes` parameter has been extended. The important changes are:
+
++ `+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`.
++ `+<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
+
+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`.
+
+All values not prefixed by a `+` will be interpreted normally.
+
+Below is an example of starting up a three node cluster using this syntax:
+
+ $ docker run -d -name node1 opendaylight/base:hydrogen -Dsupernodes=+self
+ a8435cc23e13cb4e04c3c9788789e7e831af61c735d14a33025b3dd6c76e2938
+ $ docker run -d -name node2 -link node1:n1 d44fd77ebbdf -Dsupernodes=+self:+n1
+ fa0b37dfd216291e36fd645a345751a1a6079123c99d75326a5775dce8414a93
+ $ docker run -d -name node3 -link node1:n1 d44fd77ebbdf -Dsupernodes=+self:+n1
+ 9ad6874aa85cad29736030239baf836f46ceb0c242baf873ab455674040d96b1
+
+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:
+
+ $ docker inspect -format='{{.NetworkSettings.IPAddress}}' node1
+ 172.17.0.46
+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).
Code Review / integration / packaging.git / commitdiff