summaryrefslogtreecommitdiffstats
path: root/docs/release/userguide/installguide.docker.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/release/userguide/installguide.docker.rst')
-rw-r--r--docs/release/userguide/installguide.docker.rst972
1 files changed, 972 insertions, 0 deletions
diff --git a/docs/release/userguide/installguide.docker.rst b/docs/release/userguide/installguide.docker.rst
new file mode 100644
index 00000000..7312a9f7
--- /dev/null
+++ b/docs/release/userguide/installguide.docker.rst
@@ -0,0 +1,972 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) <optionally add copywriters name>
+.. _barometer-docker-userguide:
+
+====================================
+OPNFV Barometer Docker Install Guide
+====================================
+
+.. contents::
+ :depth: 3
+ :local:
+
+The intention of this user guide is to outline how to install and test the Barometer project's
+docker images. The `OPNFV docker hub <https://hub.docker.com/u/opnfv/?page=1>`_ contains 5 docker
+images from the Barometer project:
+
+ 1. `Collectd docker image <https://hub.docker.com/r/opnfv/barometer-collectd/>`_
+ 2. `Influxdb docker image <https://hub.docker.com/r/opnfv/barometer-influxdb/>`_
+ 3. `Grafana docker image <https://hub.docker.com/r/opnfv/barometer-grafana/>`_
+ 4. `Kafka docker image <https://hub.docker.com/r/opnfv/barometer-kafka/>`_
+ 5. `VES application docker image <https://hub.docker.com/r/opnfv/barometer-ves/>`_
+
+For description of images please see section `Barometer Docker Images Description`_
+
+For steps to build and run Collectd image please see section `Build and Run Collectd Docker Image`_
+
+For steps to build and run InfluxDB and Grafana images please see section `Build and Run InfluxDB and Grafana Docker Images`_
+
+For steps to build and run VES and Kafka images please see section `Build and Run VES and Kafka Docker Images`_
+
+For overview of running VES application with Kafka please see the :ref:`VES Application User Guide <barometer-ves-userguide>`
+
+For an alternative installation method using ansible, please see the :ref:`Barometer One Click Install Guide <barometer-oneclick-userguide>`.
+
+Barometer Docker Images Description
+-----------------------------------
+
+.. Describe the specific features and how it is realised in the scenario in a brief manner
+.. to ensure the user understand the context for the user guide instructions to follow.
+
+Barometer Collectd Image
+^^^^^^^^^^^^^^^^^^^^^^^^
+The barometer collectd docker image gives you a collectd installation that includes all
+the barometer plugins.
+
+.. note::
+ The Dockerfile is available in the docker/barometer-collectd directory in the barometer repo.
+ The Dockerfile builds a CentOS 7 docker image.
+ The container MUST be run as a privileged container.
+
+Collectd is a daemon which collects system performance statistics periodically
+and provides a variety of mechanisms to publish the collected metrics. It
+supports more than 90 different input and output plugins. Input plugins
+retrieve metrics and publish them to the collectd deamon, while output plugins
+publish the data they receive to an end point. Collectd also has infrastructure
+to support thresholding and notification.
+
+Collectd docker image has enabled the following collectd plugins (in addition
+to the standard collectd plugins):
+
+* hugepages plugin
+* Open vSwitch events Plugin
+* Open vSwitch stats Plugin
+* mcelog plugin
+* PMU plugin
+* RDT plugin
+* virt
+* SNMP Agent
+* Kafka_write plugin
+
+Plugins and third party applications in Barometer repository that will be available in the
+docker image:
+
+* Open vSwitch PMD stats
+* ONAP VES application
+* gnocchi plugin
+* aodh plugin
+* Legacy/IPMI
+
+InfluxDB + Grafana Docker Images
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Barometer project's InfluxDB and Grafana docker images are 2 docker images that database and graph
+statistics reported by the Barometer collectd docker. InfluxDB is an open-source time series database
+tool which stores the data from collectd for future analysis via Grafana, which is a open-source
+metrics anlytics and visualisation suite which can be accessed through any browser.
+
+VES + Kafka Docker Images
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Barometer project's VES application and Kafka docker images are based on a CentOS 7 image. Kafka
+docker image has a dependancy on `Zookeeper <https://zookeeper.apache.org/>`_. Kafka must be able to
+connect and register with an instance of Zookeeper that is either running on local or remote host.
+Kafka recieves and stores metrics recieved from Collectd. VES application pulls latest metrics from Kafka
+which it normalizes into VES format for sending to a VES collector. Please see details in
+:ref:`VES Application User Guide <barometer-ves-userguide>`
+
+Installing Docker
+-----------------
+.. Describe the specific capabilities and usage for <XYZ> feature.
+.. Provide enough information that a user will be able to operate the feature on a deployed scenario.
+
+.. note::
+ The below sections provide steps for manual installation and configuration
+ of docker images. They are not neccessary if docker images were installed with
+ use of Ansible-Playbook.
+
+On Ubuntu
+^^^^^^^^^
+.. note::
+ * sudo permissions are required to install docker.
+ * These instructions are for Ubuntu 16.10
+
+To install docker:
+
+.. code:: bash
+
+ $ sudo apt-get install curl
+ $ sudo curl -fsSL https://get.docker.com/ | sh
+ $ sudo usermod -aG docker <username>
+ $ sudo systemctl status docker
+
+Replace <username> above with an appropriate user name.
+
+On CentOS
+^^^^^^^^^^
+.. note::
+ * sudo permissions are required to install docker.
+ * These instructions are for CentOS 7
+
+To install docker:
+
+.. code:: bash
+
+ $ sudo yum remove docker docker-common docker-selinux docker-engine
+ $ sudo yum install -y yum-utils device-mapper-persistent-data lvm2
+ $ sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
+ $ sudo yum-config-manager --enable docker-ce-edge
+ $ sudo yum-config-manager --enable docker-ce-test
+ $ sudo yum install docker-ce
+ $ sudo usermod -aG docker <username>
+ $ sudo systemctl status docker
+
+Replace <username> above with an appropriate user name.
+
+.. note::
+ If this is the first time you are installing a package from a recently added
+ repository, you will be prompted to accept the GPG key, and the key’s
+ fingerprint will be shown. Verify that the fingerprint is correct, and if so,
+ accept the key. The fingerprint should match060A 61C5 1B55 8A7F 742B 77AA C52F
+ EB6B 621E 9F35.
+
+ Retrieving key from https://download.docker.com/linux/centos/gpg
+ Importing GPG key 0x621E9F35:
+ Userid : "Docker Release (CE rpm) <docker@docker.com>"
+ Fingerprint: 060a 61c5 1b55 8a7f 742b 77aa c52f eb6b 621e 9f35
+ From : https://download.docker.com/linux/centos/gpg
+ Is this ok [y/N]: y
+
+Manual proxy configuration for docker
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+ This applies for both CentOS and Ubuntu.
+
+If you are behind an HTTP or HTTPS proxy server, you will need to add this
+configuration in the Docker systemd service file.
+
+1. Create a systemd drop-in directory for the docker service:
+
+.. code:: bash
+
+ $ sudo mkdir -p /etc/systemd/system/docker.service.d
+
+2. Create a file
+called /etc/systemd/system/docker.service.d/http-proxy.conf that adds
+the HTTP_PROXY environment variable:
+
+.. code:: bash
+
+ [Service]
+ Environment="HTTP_PROXY=http://proxy.example.com:80/"
+
+Or, if you are behind an HTTPS proxy server, create a file
+called /etc/systemd/system/docker.service.d/https-proxy.conf that adds
+the HTTPS_PROXY environment variable:
+
+.. code:: bash
+
+ [Service]
+ Environment="HTTPS_PROXY=https://proxy.example.com:443/"
+
+Or create a single file with all the proxy configurations:
+/etc/systemd/system/docker.service.d/proxy.conf
+
+.. code:: bash
+
+ [Service]
+ Environment="HTTP_PROXY=http://proxy.example.com:80/"
+ Environment="HTTPS_PROXY=https://proxy.example.com:443/"
+ Environment="FTP_PROXY=ftp://proxy.example.com:443/"
+ Environment="NO_PROXY=localhost"
+
+3. Flush changes:
+
+.. code:: bash
+
+ $ sudo systemctl daemon-reload
+
+4. Restart Docker:
+
+.. code:: bash
+
+ $ sudo systemctl restart docker
+
+5. Check docker environment variables:
+
+.. code:: bash
+
+ sudo systemctl show --property=Environment docker
+
+Test docker installation
+^^^^^^^^^^^^^^^^^^^^^^^^
+.. note::
+ This applies for both CentOS and Ubuntu.
+
+.. code:: bash
+
+ $ sudo docker run hello-world
+
+The output should be something like:
+
+.. code:: bash
+
+ Unable to find image 'hello-world:latest' locally
+ latest: Pulling from library/hello-world
+ 5b0f327be733: Pull complete
+ Digest: sha256:07d5f7800dfe37b8c2196c7b1c524c33808ce2e0f74e7aa00e603295ca9a0972
+ Status: Downloaded newer image for hello-world:latest
+
+ Hello from Docker!
+ This message shows that your installation appears to be working correctly.
+
+ To generate this message, Docker took the following steps:
+ 1. The Docker client contacted the Docker daemon.
+ 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
+ 3. The Docker daemon created a new container from that image which runs the
+ executable that produces the output you are currently reading.
+ 4. The Docker daemon streamed that output to the Docker client, which sent it
+ to your terminal.
+
+To try something more ambitious, you can run an Ubuntu container with:
+
+.. code:: bash
+
+ $ docker run -it ubuntu bash
+
+Build and Run Collectd Docker Image
+-----------------------------------
+
+Collectd-barometer flavors
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Before starting to build and run the Collectd container, understand the available
+flavors of Collectd containers:
+ * barometer-collectd - stable release, based on collectd 5.8
+ * barometer-collectd-master - release based on collectd 'master' branch
+ * barometer-collectd-experimental - release based on collectd 'master'
+ branch that also includes set of experimental(not yet merged into upstream)
+ pull requests
+
+.. note::
+ Experimental container is not tested across various OS'es and the stability
+ of the container can change. Usage of experimental flavor is at users risk.
+
+Stable barometer-collectd container is intended for work in production
+environment as it is based on latest collectd official release.
+`Barometer-collectd-master` and `barometer-collectd-experimental` containers
+can be used in order to try new collectd features.
+All flavors are located in `barometer` git repository - respective dockerfiles
+are stored in subdirectories of 'docker/' directory
+
+
+.. code:: bash
+
+ $ git clone https://gerrit.opnfv.org/gerrit/barometer
+ $ ls barometer/docker|grep collectd
+ barometer-collectd
+ barometer-collectd-master
+ barometer-collectd-experimental
+
+.. note::
+ Main directory of barometer source code (directory that contains 'docker',
+ 'docs', 'src' and systems sub-directories) will be referred as
+ ``<BAROMETER_REPO_DIR>``
+
+Download the collectd docker image
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+If you wish to use a pre-built barometer image, you can pull the barometer
+image from https://hub.docker.com/r/opnfv/barometer-collectd/
+
+.. code:: bash
+
+ $ docker pull opnfv/barometer-collectd
+
+Build stable collectd container
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code:: bash
+
+ $ cd <BAROMETER_REPO_DIR>/docker/barometer-collectd
+ $ sudo docker build -t opnfv/barometer-collectd --build-arg http_proxy=`echo $http_proxy` \
+ --build-arg https_proxy=`echo $https_proxy` --network=host -f Dockerfile .
+
+.. note::
+ In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs to be
+ passed only if system is behind an HTTP or HTTPS proxy server.
+
+Check the docker images:
+
+.. code:: bash
+
+ $ sudo docker images
+
+Output should contain a barometer-collectd image:
+
+.. code::
+
+ REPOSITORY TAG IMAGE ID CREATED SIZE
+ opnfv/barometer-collectd latest 05f2a3edd96b 3 hours ago 1.2GB
+ centos 7 196e0ce0c9fb 4 weeks ago 197MB
+ centos latest 196e0ce0c9fb 4 weeks ago 197MB
+ hello-world latest 05a3bd381fc2 4 weeks ago 1.84kB
+
+.. note::
+ If you do not plan to use collectd-master and collectd-experimental barometer
+ containers, then you can proceed directly to section `Run the collectd stable docker image`_
+
+
+Build collectd-master container
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code:: bash
+
+ $ cd <BAROMETER_REPO_DIR>
+ $ sudo docker build -t opnfv/barometer-collectd-master \
+ --build-arg http_proxy=`echo $http_proxy` \
+ --build-arg https_proxy=`echo $https_proxy` --network=host -f \
+ docker/barometer-collectd-master/Dockerfile .
+
+.. note::
+ For `barometer-collectd-master` and `barometer-collectd-experimental` containers
+ proxy parameters should be passed only if system is behind an HTTP or HTTPS
+ proxy server (same as for stable collectd container)
+
+Build collectd-experimental container
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code:: bash
+
+ $ cd <BAROMETER_REPO_DIR>
+ $ sudo docker build -t opnfv/barometer-collectd-experimental \
+ --build-arg http_proxy=`echo $http_proxy` \
+ --build-arg https_proxy=`echo $https_proxy` \
+ --network=host -f docker/barometer-collectd-experimental/Dockerfile .
+
+.. note::
+ For `barometer-collectd-master` and `barometer-collectd-experimental` containers
+ proxy parameters should be passed only if system is behind an HTTP or HTTPS
+ proxy server (same as for stable collectd container)
+
+Run the collectd stable docker image
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. code:: bash
+
+ $ cd <BAROMETER_REPO_DIR>
+ $ sudo docker run -ti --net=host -v \
+ `pwd`/src/collectd/collectd_sample_configs:/opt/collectd/etc/collectd.conf.d \
+ -v /var/run:/var/run -v /tmp:/tmp --privileged opnfv/barometer-collectd
+
+.. note::
+ The docker collectd image contains configuration for all the collectd
+ plugins. In the command above we are overriding
+ /opt/collectd/etc/collectd.conf.d by mounting a host directory
+ src/collectd/collectd_sample_configs that contains only the sample
+ configurations we are interested in running.
+
+ *If some dependencies for plugins listed in configuration directory
+ aren't met, then collectd startup may fail(collectd tries to
+ initialize plugins configurations for all given config files that can
+ be found in shared configs directory and may fail if some dependency
+ is missing).*
+
+ If `DPDK` or `RDT` can't be installed on host, then corresponding config
+ files should be removed from shared configuration directory
+ (`<BAROMETER_REPO_DIR>/src/collectd/collectd_sample_configs/`) prior
+ to starting barometer-collectd container. By example: in case of missing
+ `DPDK` functionality on the host, `dpdkstat.conf` and `dpdkevents.conf`
+ should be removed.
+
+ Sample configurations can be found at:
+ https://github.com/opnfv/barometer/tree/master/src/collectd/collectd_sample_configs
+
+ List of barometer-collectd dependencies on host for various plugins
+ can be found at:
+ https://wiki.opnfv.org/display/fastpath/Barometer-collectd+host+dependencies
+
+Check your docker image is running
+
+.. code:: bash
+
+ sudo docker ps
+
+To make some changes when the container is running run:
+
+.. code:: bash
+
+ sudo docker exec -ti <CONTAINER ID> /bin/bash
+
+Run the barometer-collectd-master docker image
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Run command for `barometer-collectd-master` container is very similar to command
+used for stable container - the only differences are name of the image
+and location of the sample configuration files(as different version of collectd
+plugins requiring different configuration files)
+
+
+.. code:: bash
+
+ $ cd <BAROMETER_REPO_DIR>
+ $ sudo docker run -ti --net=host -v \
+ `pwd`/src/collectd/collectd_sample_configs-master:/opt/collectd/etc/collectd.conf.d \
+ -v /var/run:/var/run -v /tmp:/tmp --privileged opnfv/barometer-collectd-master
+
+.. note::
+ Barometer collectd docker images are sharing some directories with host
+ (e.g. /tmp) therefore only one of collectd barometer flavors can be run
+ at a time. In other words, if you want to try `barometer-collectd-master` or
+ `barometer-collectd-experimental` image, please stop instance of
+ `barometer-collectd(stable)` image first.
+
+Run the barometer-collectd-experimental docker image
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Barometer-collectd-experimental container shares default configuration files
+with 'barometer-collectd-master' equivalent but some of experimental pull
+requests may require modified configuration. Additional configuration files that
+are required specifically by experimental container can be found in
+`docker/barometer-collectd-experimental/experimental-configs/`
+directory. Content of this directory (all \*.conf files) should be copied to
+`src/collectd/collectd_sample_configs-master` directory before first run of
+experimental container.
+
+.. code:: bash
+
+ $ cd <BAROMETER_REPO_DIR>
+ $ cp docker/barometer-collectd-experimental/experimental-configs/*.conf \
+ src/collectd/collectd_sample_configs-master
+
+When configuration files are up to date for experimental container, it can be
+launched using following command (almost identical to run-command for 'master'
+collectd container)
+
+.. code:: bash
+
+ $ cd <BAROMETER_REPO_DIR>
+ $ sudo docker run -ti --net=host -v \
+ `pwd`/src/collectd/collectd_sample_configs-master:/opt/collectd/etc/collectd.conf.d \
+ -v /var/run:/var/run -v /tmp:/tmp --privileged \
+ opnfv/barometer-collectd-experimental
+
+
+Build and Run InfluxDB and Grafana docker images
+------------------------------------------------
+
+Overview
+^^^^^^^^
+The barometer-influxdb image is based on the influxdb:1.3.7 image from the influxdb dockerhub. To
+view detils on the base image please visit
+`https://hub.docker.com/_/influxdb/ <https://hub.docker.com/_/influxdb/>`_ Page includes details of
+exposed ports and configurable enviromental variables of the base image.
+
+The barometer-grafana image is based on grafana:4.6.3 image from the grafana dockerhub. To view
+details on the base image please visit
+`https://hub.docker.com/r/grafana/grafana/ <https://hub.docker.com/r/grafana/grafana/>`_ Page
+includes details on exposed ports and configurable enviromental variables of the base image.
+
+The barometer-grafana image includes pre-configured source and dashboards to display statistics exposed
+by the barometer-collectd image. The default datasource is an influxdb database running on localhost
+but the address of the influxdb server can be modified when launching the image by setting the
+environmental variables influxdb_host to IP or hostname of host on which influxdb server is running.
+
+Additional dashboards can be added to barometer-grafana by mapping a volume to /opt/grafana/dashboards.
+Incase where a folder is mounted to this volume only files included in this folder will be visible
+inside barometer-grafana. To ensure all default files are also loaded please ensure they are included in
+volume folder been mounted. Appropriate example are given in section `Run the Grafana docker image`_
+
+Download the InfluxDB and Grafana docker images
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+If you wish to use pre-built barometer project's influxdb and grafana images, you can pull the
+images from https://hub.docker.com/r/opnfv/barometer-influxdb/ and https://hub.docker.com/r/opnfv/barometer-grafana/
+
+.. note::
+ If your preference is to build images locally please see sections `Build InfluxDB Docker Image`_ and
+ `Build Grafana Docker Image`_
+
+.. code:: bash
+
+ $ docker pull opnfv/barometer-influxdb
+ $ docker pull opnfv/barometer-grafana
+
+.. note::
+ If you have pulled the pre-built barometer-influxdb and barometer-grafana images there is no
+ requirement to complete steps outlined in sections `Build InfluxDB Docker Image`_ and
+ `Build Grafana Docker Image`_ and you can proceed directly to section
+ `Run the Influxdb and Grafana Images`_
+
+Build InfluxDB docker image
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Build influxdb image from Dockerfile
+
+.. code:: bash
+
+ $ cd barometer/docker/barometer-influxdb
+ $ sudo docker build -t opnfv/barometer-influxdb --build-arg http_proxy=`echo $http_proxy` \
+ --build-arg https_proxy=`echo $https_proxy` --network=host -f Dockerfile .
+
+.. note::
+ In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs to
+ be passed only if system is behind an HTTP or HTTPS proxy server.
+
+Check the docker images:
+
+.. code:: bash
+
+ $ sudo docker images
+
+Output should contain an influxdb image:
+
+.. code::
+
+ REPOSITORY TAG IMAGE ID CREATED SIZE
+ opnfv/barometer-influxdb latest 1e4623a59fe5 3 days ago 191MB
+
+Build Grafana docker image
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Build Grafana image from Dockerfile
+
+.. code:: bash
+
+ $ cd barometer/docker/barometer-grafana
+ $ sudo docker build -t opnfv/barometer-grafana --build-arg http_proxy=`echo $http_proxy` \
+ --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
+
+.. note::
+ In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs to
+ be passed only if system is behind an HTTP or HTTPS proxy server.
+
+Check the docker images:
+
+.. code:: bash
+
+ $ sudo docker images
+
+Output should contain an influxdb image:
+
+.. code::
+
+ REPOSITORY TAG IMAGE ID CREATED SIZE
+ opnfv/barometer-grafana latest 05f2a3edd96b 3 hours ago 1.2GB
+
+Run the Influxdb and Grafana Images
+-----------------------------------
+
+Run the InfluxDB docker image
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. code:: bash
+
+ $ sudo docker run -tid -v /var/lib/influxdb:/var/lib/influxdb --net=host\
+ --name bar-influxdb opnfv/barometer-influxdb
+
+Check your docker image is running
+
+.. code:: bash
+
+ sudo docker ps
+
+To make some changes when the container is running run:
+
+.. code:: bash
+
+ sudo docker exec -ti <CONTAINER ID> /bin/bash
+
+When both collectd and InfluxDB containers are located
+on the same host, then no additional configuration have to be added and you
+can proceed directly to `Run the Grafana docker image`_ section.
+
+Modify collectd to support InfluxDB on another host
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+If InfluxDB and collectd containers are located on separate hosts, then
+additional configuration have to be done in ``collectd`` container - it
+normally sends data using network plugin to 'localhost/127.0.0.1' therefore
+changing output location is required:
+
+1. Stop and remove running bar-collectd container (if it is running)
+
+ .. code:: bash
+
+ $ sudo docker ps #to get collectd container name
+ $ sudo docker rm -f <COLLECTD_CONTAINER_NAME>
+
+2. Go to location where shared collectd config files are stored
+
+ .. code:: bash
+
+ $ cd <BAROMETER_REPO_DIR>
+ $ cd src/collectd/collectd_sample_configs
+
+3. Edit content of ``network.conf`` file.
+ By default this file looks like that:
+
+ .. code::
+
+ LoadPlugin network
+ <Plugin network>
+ Server "127.0.0.1" "25826"
+ </Plugin>
+
+ ``127.0.0.1`` string has to be replaced with the IP address of host where
+ InfluxDB container is running (e.g. ``192.168.121.111``). Edit this using your
+ favorite text editor.
+
+4. Start again collectd container like it is described in
+ `Run the collectd stable docker image`_ chapter
+
+ .. code:: bash
+
+ $ cd <BAROMETER_REPO_DIR>
+ $ sudo docker run -ti --name bar-collectd --net=host -v \
+ `pwd`/src/collectd/collectd_sample_configs:/opt/collectd/etc/collectd.conf.d \
+ -v /var/run:/var/run -v /tmp:/tmp --privileged opnfv/barometer-collectd
+
+Now collectd container will be sending data to InfluxDB container located on
+remote Host pointed by IP configured in step 3.
+
+Run the Grafana docker image
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Connecting to an influxdb instance running on local system and adding own custom dashboards
+
+.. code:: bash
+
+ $ cd <BAROMETER_REPO_DIR>
+ $ sudo docker run -tid -v /var/lib/grafana:/var/lib/grafana \
+ -v ${PWD}/docker/barometer-grafana/dashboards:/opt/grafana/dashboards \
+ --name bar-grafana --net=host opnfv/barometer-grafana
+
+Connecting to an influxdb instance running on remote system with hostname of someserver and IP address
+of 192.168.121.111
+
+.. code:: bash
+
+ $ sudo docker run -tid -v /var/lib/grafana:/var/lib/grafana --net=host -e \
+ influxdb_host=someserver --add-host someserver:192.168.121.111 --name \
+ bar-grafana opnfv/barometer-grafana
+
+Check your docker image is running
+
+.. code:: bash
+
+ sudo docker ps
+
+To make some changes when the container is running run:
+
+.. code:: bash
+
+ sudo docker exec -ti <CONTAINER ID> /bin/bash
+
+Connect to <host_ip>:3000 with a browser and log into grafana: admin/admin
+
+Cleanup of influxdb/grafana configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When user wants to remove current grafana and influxdb configuration,
+folowing actions have to be performed
+
+1. Stop and remove running influxdb and grafana containers
+
+.. code:: bash
+
+ sudo docker rm -f bar-grafana bar-influxdb
+
+2. Remove shared influxdb and grafana folders from the Host
+
+.. code:: bash
+
+ sudo rm -rf /var/lib/grafana
+ sudo rm -rf /var/lib/influxdb
+
+.. note::
+ Shared folders are storing configuration of grafana and influxdb
+ containers. In case of changing influxdb or grafana configuration
+ (e.g. moving influxdb to another host) it is good to perform cleanup
+ on shared folders to not affect new setup with an old configuration.
+
+Build and Run VES and Kafka Docker Images
+-----------------------------------------
+
+Download VES and Kafka docker images
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you wish to use pre-built barometer project's VES and kafka images, you can pull the
+images from https://hub.docker.com/r/opnfv/barometer-ves/ and https://hub.docker.com/r/opnfv/barometer-kafka/
+
+.. note::
+ If your preference is to build images locally please see sections `Build the Kafka Image`_ and
+ `Build VES Image`_
+
+.. code:: bash
+
+ $ docker pull opnfv/barometer-kafka
+ $ docker pull opnfv/barometer-ves
+
+.. note::
+ If you have pulled the pre-built images there is no requirement to complete steps outlined
+ in sections `Build Kafka Docker Image`_ and `Build VES Docker Image`_ and you can proceed directly to section
+ `Run Kafka Docker Image`_
+
+Build Kafka docker image
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Build Kafka docker image:
+
+.. code:: bash
+
+ $ cd barometer/docker/barometer-kafka
+ $ sudo docker build -t opnfv/barometer-kafka --build-arg http_proxy=`echo $http_proxy` \
+ --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
+
+.. note::
+ In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs
+ to be passed only if system is behind an HTTP or HTTPS proxy server.
+
+Check the docker images:
+
+.. code:: bash
+
+ $ sudo docker images
+
+Output should contain a barometer image:
+
+.. code::
+
+ REPOSITORY TAG IMAGE ID CREATED SIZE
+ opnfv/barometer-kafka latest 05f2a3edd96b 3 hours ago 1.2GB
+
+Build VES docker image
+^^^^^^^^^^^^^^^^^^^^^^
+
+Build VES application docker image:
+
+.. code:: bash
+
+ $ cd barometer/docker/barometer-ves
+ $ sudo docker build -t opnfv/barometer-ves --build-arg http_proxy=`echo $http_proxy` \
+ --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
+
+.. note::
+ In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs
+ to be passed only if system is behind an HTTP or HTTPS proxy server.
+
+Check the docker images:
+
+.. code:: bash
+
+ $ sudo docker images
+
+Output should contain a barometer image:
+
+.. code::
+
+ REPOSITORY TAG IMAGE ID CREATED SIZE
+ opnfv/barometer-ves latest 05f2a3edd96b 3 hours ago 1.2GB
+
+Run Kafka docker image
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+ Before running Kafka an instance of Zookeeper must be running for the Kafka broker to register
+ with. Zookeeper can be running locally or on a remote platform. Kafka's broker_id and address of
+ its zookeeper instance can be configured by setting values for environmental variables 'broker_id'
+ and 'zookeeper_node'. In instance where 'broker_id' and/or 'zookeeper_node' is not set the default
+ setting of broker_id=0 and zookeeper_node=localhost is used. In intance where Zookeeper is running
+ on same node as Kafka and there is a one to one relationship between Zookeeper and Kafka, default
+ setting can be used. The docker argument `add-host` adds hostname and IP address to
+ /etc/hosts file in container
+
+Run zookeeper docker image:
+
+.. code:: bash
+
+ $ sudo docker run -tid --net=host -p 2181:2181 zookeeper:3.4.11
+
+Run kafka docker image which connects with a zookeeper instance running on same node with a 1:1 relationship
+
+.. code:: bash
+
+ $ sudo docker run -tid --net=host -p 9092:9092 opnfv/barometer-kafka
+
+
+Run kafka docker image which connects with a zookeeper instance running on a node with IP address of
+192.168.121.111 using broker ID of 1
+
+.. code:: bash
+
+ $ sudo docker run -tid --net=host -p 9092:9092 --env broker_id=1 --env zookeeper_node=zookeeper --add-host \
+ zookeeper:192.168.121.111 opnfv/barometer-kafka
+
+Run VES Application docker image
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. note::
+ VES application uses configuration file ves_app_config.conf from directory
+ barometer/3rd_party/collectd-ves-app/ves_app/config/ and host.yaml file from
+ barometer/3rd_party/collectd-ves-app/ves_app/yaml/ by default. If you wish to use a custom config
+ file it should be mounted to mount point /opt/ves/config/ves_app_config.conf. To use an alternative yaml
+ file from folder barometer/3rd_party/collectd-ves-app/ves_app/yaml the name of the yaml file to use
+ should be passed as an additional command. If you wish to use a custom file the file should be
+ mounted to mount point /opt/ves/yaml/ Please see examples below
+
+Run VES docker image with default configuration
+
+.. code:: bash
+
+ $ sudo docker run -tid --net=host opnfv/barometer-ves
+
+Run VES docker image with guest.yaml files from barometer/3rd_party/collectd-ves-app/ves_app/yaml/
+
+.. code:: bash
+
+ $ sudo docker run -tid --net=host opnfv/barometer-ves guest.yaml
+
+
+Run VES docker image with using custom config and yaml files. In example below yaml/ folder cotains
+file named custom.yaml
+
+.. code:: bash
+
+ $ sudo docker run -tid --net=host -v ${PWD}/custom.config:/opt/ves/config/ves_app_config.conf \
+ -v ${PWD}/yaml/:/opt/ves/yaml/ opnfv/barometer-ves custom.yaml
+
+Run VES Test Collector application
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+VES Test Collector application can be used for displaying platform
+wide metrics that are collected by barometer-ves container.
+Setup instructions are located in: :ref:`Setup VES Test Collector`
+
+Build and Run DMA and Redis Docker Images
+-----------------------------------------
+
+Download DMA docker images
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you wish to use pre-built barometer project's DMA images, you can pull the
+images from https://hub.docker.com/r/opnfv/barometer-dma/
+
+.. note::
+ If your preference is to build images locally please see sections `Build DMA Docker Image`_
+
+.. code:: bash
+
+ $ docker pull opnfv/barometer-dma
+
+.. note::
+ If you have pulled the pre-built images there is no requirement to complete steps outlined
+ in sections `Build DMA Docker Image`_ and you can proceed directly to section
+ `Run DMA Docker Image`_
+
+Build DMA docker image
+^^^^^^^^^^^^^^^^^^^^^^
+
+Build DMA docker image:
+
+.. code:: bash
+
+ $ cd barometer/docker/barometer-dma
+ $ sudo docker build -t opnfv/barometer-dma --build-arg http_proxy=`echo $http_proxy` \
+ --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
+
+.. note::
+ In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs
+ to be passed only if system is behind an HTTP or HTTPS proxy server.
+
+Check the docker images:
+
+.. code:: bash
+
+ $ sudo docker images
+
+Output should contain a barometer image:
+
+.. code::
+
+ REPOSITORY TAG IMAGE ID CREATED SIZE
+ opnfv/barometer-dma latest 2f14fbdbd498 3 hours ago 941 MB
+
+Run Redis docker image
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+ Before running DMA, Redis must be running.
+
+Run Redis docker image:
+
+.. code:: bash
+
+ $ sudo docker run -tid -p 6379:6379 --name barometer-redis redis
+
+Check your docker image is running
+
+.. code:: bash
+
+ sudo docker ps
+
+Run DMA docker image
+^^^^^^^^^^^^^^^^^^^^
+.. note::
+
+Run DMA docker image with default configuration
+
+.. code:: bash
+
+ $ cd barometer/docker/barometer-dma
+ $ sudo mkdir /etc/barometer-dma
+ $ sudo cp ../../src/dma/examples/config.toml /etc/barometer-dma/
+ $ sudo vi /etc/barometer-dma/config.toml
+ (edit amqp_password and os_password:OpenStack admin password)
+
+ $ sudo su -
+ (When there is no key for SSH access authentication)
+ # ssh-keygen
+ (Press Enter until done)
+ (Backup if necessary)
+ # cp ~/.ssh/authorized_keys ~/.ssh/authorized_keys_org
+ # cat ~/.ssh/authorized_keys_org ~/.ssh/id_rsa.pub \
+ > ~/.ssh/authorized_keys
+ # exit
+
+ $ sudo docker run -tid --net=host --name server \
+ -v /etc/barometer-dma:/etc/barometer-dma \
+ -v /root/.ssh/id_rsa:/root/.ssh/id_rsa \
+ -v /etc/collectd/collectd.conf.d:/etc/collectd/collectd.conf.d \
+ opnfv/barometer-dma /server
+
+ $ sudo docker run -tid --net=host --name infofetch \
+ -v /etc/barometer-dma:/etc/barometer-dma \
+ -v /var/run/libvirt:/var/run/libvirt \
+ opnfv/barometer-dma /infofetch
+
+ (Execute when installing the threshold evaluation binary)
+ $ sudo docker cp infofetch:/threshold ./
+ $ sudo ln -s ${PWD}/threshold /usr/local/bin/
+
+References
+^^^^^^^^^^
+.. [1] https://docs.docker.com/engine/admin/systemd/#httphttps-proxy
+.. [2] https://docs.docker.com/engine/installation/linux/docker-ce/centos/#install-using-the-repository
+.. [3] https://docs.docker.com/engine/userguide/
+
+