docs/release/userguide/installguide.docker.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. (c) <optionally add copywriters name>
   4 .. _barometer-docker-userguide:
   5
   6 ====================================
   7 OPNFV Barometer Docker Install Guide
   8 ====================================
   9
  10 .. contents::
  11    :depth: 3
  12    :local:
  13
  14 The intention of this user guide is to outline how to install and test the Barometer project's
  15 docker images. The `OPNFV docker hub <https://hub.docker.com/u/opnfv/?page=1>`_ contains 5 docker
  16 images from the Barometer project:
  17
  18  1. `Collectd docker image <https://hub.docker.com/r/opnfv/barometer-collectd/>`_
  19  2. `Influxdb docker image <https://hub.docker.com/r/opnfv/barometer-influxdb/>`_
  20  3. `Grafana docker image <https://hub.docker.com/r/opnfv/barometer-grafana/>`_
  21  4. `Kafka docker image <https://hub.docker.com/r/opnfv/barometer-kafka/>`_
  22  5. `VES application docker image <https://hub.docker.com/r/opnfv/barometer-ves/>`_
  23
  24 For description of images please see section `Barometer Docker Images Description`_
  25
  26 For steps to build and run Collectd image please see section `Build and Run Collectd Docker Image`_
  27
  28 For steps to build and run InfluxDB and Grafana images please see section `Build and Run InfluxDB and Grafana Docker Images`_
  29
  30 For steps to build and run VES and Kafka images please see section `Build and Run VES and Kafka Docker Images`_
  31
  32 For overview of running VES application with Kafka please see the :ref:`VES Application User Guide <barometer-ves-userguide>`
  33
  34 For an alternative installation method using ansible, please see the :ref:`Barometer One Click Install Guide <barometer-oneclick-userguide>`.
  35
  36 Barometer Docker Images Description
  37 -----------------------------------
  38
  39 .. Describe the specific features and how it is realised in the scenario in a brief manner
  40 .. to ensure the user understand the context for the user guide instructions to follow.
  41
  42 Barometer Collectd Image
  43 ^^^^^^^^^^^^^^^^^^^^^^^^
  44 The barometer collectd docker image gives you a collectd installation that includes all
  45 the barometer plugins.
  46
  47 .. note::
  48    The Dockerfile is available in the docker/barometer-collectd directory in the barometer repo.
  49    The Dockerfile builds a CentOS 7 docker image.
  50    The container MUST be run as a privileged container.
  51
  52 Collectd is a daemon which collects system performance statistics periodically
  53 and provides a variety of mechanisms to publish the collected metrics. It
  54 supports more than 90 different input and output plugins. Input plugins
  55 retrieve metrics and publish them to the collectd deamon, while output plugins
  56 publish the data they receive to an end point. Collectd also has infrastructure
  57 to support thresholding and notification.
  58
  59 Collectd docker image has enabled the following collectd plugins (in addition
  60 to the standard collectd plugins):
  61
  62 * hugepages plugin
  63 * Open vSwitch events Plugin
  64 * Open vSwitch stats Plugin
  65 * mcelog plugin
  66 * PMU plugin
  67 * RDT plugin
  68 * virt
  69 * SNMP Agent
  70 * Kafka_write plugin
  71
  72 Plugins and third party applications in Barometer repository that will be available in the
  73 docker image:
  74
  75 * Open vSwitch PMD stats
  76 * ONAP VES application
  77 * gnocchi plugin
  78 * aodh plugin
  79 * Legacy/IPMI
  80
  81 InfluxDB + Grafana Docker Images
  82 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  83
  84 The Barometer project's InfluxDB and Grafana docker images are 2 docker images that database and graph
  85 statistics reported by the Barometer collectd docker. InfluxDB is an open-source time series database
  86 tool which stores the data from collectd for future analysis via Grafana, which is a open-source
  87 metrics anlytics and visualisation suite which can be accessed through any browser.
  88
  89 VES + Kafka Docker Images
  90 ^^^^^^^^^^^^^^^^^^^^^^^^^
  91
  92 The Barometer project's VES application and Kafka docker images are based on a CentOS 7 image. Kafka
  93 docker image has a dependancy on `Zookeeper <https://zookeeper.apache.org/>`_. Kafka must be able to
  94 connect and register with an instance of Zookeeper that is either running on local or remote host.
  95 Kafka recieves and stores metrics recieved from Collectd. VES application pulls latest metrics from Kafka
  96 which it normalizes into VES format for sending to a VES collector. Please see details in
  97 :ref:`VES Application User Guide <barometer-ves-userguide>`
  98
  99 Installing Docker
 100 -----------------
 101 .. Describe the specific capabilities and usage for <XYZ> feature.
 102 .. Provide enough information that a user will be able to operate the feature on a deployed scenario.
 103
 104 .. note::
 105    The below sections provide steps for manual installation and configuration
 106    of docker images. They are not neccessary if docker images were installed with
 107    use of Ansible-Playbook.
 108
 109 On Ubuntu
 110 ^^^^^^^^^
 111 .. note::
 112    * sudo permissions are required to install docker.
 113    * These instructions are for Ubuntu 16.10
 114
 115 To install docker:
 116
 117 .. code:: bash
 118
 119     $ sudo apt-get install curl
 120     $ sudo curl -fsSL https://get.docker.com/ | sh
 121     $ sudo usermod -aG docker <username>
 122     $ sudo systemctl status docker
 123
 124 Replace <username> above with an appropriate user name.
 125
 126 On CentOS
 127 ^^^^^^^^^^
 128 .. note::
 129    * sudo permissions are required to install docker.
 130    * These instructions are for CentOS 7
 131
 132 To install docker:
 133
 134 .. code:: bash
 135
 136     $ sudo yum remove docker docker-common docker-selinux docker-engine
 137     $ sudo yum install -y yum-utils  device-mapper-persistent-data  lvm2
 138     $ sudo yum-config-manager   --add-repo    https://download.docker.com/linux/centos/docker-ce.repo
 139     $ sudo yum-config-manager --enable docker-ce-edge
 140     $ sudo yum-config-manager --enable docker-ce-test
 141     $ sudo yum install docker-ce
 142     $ sudo usermod -aG docker <username>
 143     $ sudo systemctl status docker
 144
 145 Replace <username> above with an appropriate user name.
 146
 147 .. note::
 148    If this is the first time you are installing a package from a recently added
 149    repository, you will be prompted to accept the GPG key, and the key’s
 150    fingerprint will be shown. Verify that the fingerprint is correct, and if so,
 151    accept the key. The fingerprint should match060A 61C5 1B55 8A7F 742B 77AA C52F
 152    EB6B 621E 9F35.
 153
 154         Retrieving key from https://download.docker.com/linux/centos/gpg
 155         Importing GPG key 0x621E9F35:
 156 .. ::
 157          Userid     : "Docker Release (CE rpm) <docker@docker.com>"
 158          Fingerprint: 060a 61c5 1b55 8a7f 742b 77aa c52f eb6b 621e 9f35
 159          From       : https://download.docker.com/linux/centos/gpg
 160         Is this ok [y/N]: y
 161
 162 Manual proxy configuration for docker
 163 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 164
 165 .. note::
 166    This applies for both CentOS and Ubuntu.
 167
 168 If you are behind an HTTP or HTTPS proxy server, you will need to add this
 169 configuration in the Docker systemd service file.
 170
 171 1. Create a systemd drop-in directory for the docker service:
 172
 173 .. code:: bash
 174
 175    $ sudo mkdir -p /etc/systemd/system/docker.service.d
 176
 177 2. Create a file
 178 called /etc/systemd/system/docker.service.d/http-proxy.conf that adds
 179 the HTTP_PROXY environment variable:
 180
 181 .. code:: bash
 182
 183    [Service]
 184    Environment="HTTP_PROXY=http://proxy.example.com:80/"
 185
 186 Or, if you are behind an HTTPS proxy server, create a file
 187 called /etc/systemd/system/docker.service.d/https-proxy.conf that adds
 188 the HTTPS_PROXY environment variable:
 189
 190 .. code:: bash
 191
 192     [Service]
 193     Environment="HTTPS_PROXY=https://proxy.example.com:443/"
 194
 195 Or create a single file with all the proxy configurations:
 196 /etc/systemd/system/docker.service.d/proxy.conf
 197
 198 .. code:: bash
 199
 200     [Service]
 201     Environment="HTTP_PROXY=http://proxy.example.com:80/"
 202     Environment="HTTPS_PROXY=https://proxy.example.com:443/"
 203     Environment="FTP_PROXY=ftp://proxy.example.com:443/"
 204     Environment="NO_PROXY=localhost"
 205
 206 3. Flush changes:
 207
 208 .. code:: bash
 209
 210     $ sudo systemctl daemon-reload
 211
 212 4. Restart Docker:
 213
 214 .. code:: bash
 215
 216     $ sudo systemctl restart docker
 217
 218 5. Check docker environment variables:
 219
 220 .. code:: bash
 221
 222     sudo systemctl show --property=Environment docker
 223
 224 Test docker installation
 225 ^^^^^^^^^^^^^^^^^^^^^^^^
 226 .. note::
 227    This applies for both CentOS and Ubuntu.
 228
 229 .. code:: bash
 230
 231    $ sudo docker run hello-world
 232
 233 The output should be something like:
 234
 235 .. code:: bash
 236
 237    Trying to pull docker.io/library/hello-world...Getting image source signatures
 238    Copying blob 0e03bdcc26d7 done
 239    Copying config bf756fb1ae done
 240    Writing manifest to image destination
 241    Storing signatures
 242
 243    Hello from Docker!
 244    This message shows that your installation appears to be working correctly.
 245
 246    To generate this message, Docker took the following steps:
 247     1. The Docker client contacted the Docker daemon.
 248     2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
 249     3. The Docker daemon created a new container from that image which runs the
 250        executable that produces the output you are currently reading.
 251     4. The Docker daemon streamed that output to the Docker client, which sent it
 252        to your terminal.
 253
 254    To try something more ambitious, you can run an Ubuntu container with:
 255     $ docker run -it ubuntu bash
 256
 257    Share images, automate workflows, and more with a free Docker ID:
 258     https://hub.docker.com/
 259
 260    For more examples and ideas, visit:
 261     https://docs.docker.com/get-started/
 262
 263 Build and Run Collectd Docker Image
 264 -----------------------------------
 265
 266 Collectd-barometer flavors
 267 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 268
 269 Before starting to build and run the Collectd container, understand the available
 270 flavors of Collectd containers:
 271   * barometer-collectd - stable release, based on collectd 5.11
 272   * barometer-collectd-master - release based on collectd 'main' branch
 273   * barometer-collectd-experimental - release based on collectd 'main'
 274     branch that also includes set of experimental (not yet merged into upstream)
 275     pull requests
 276
 277 .. note::
 278    Experimental container is not tested across various OS'es and the stability
 279    of the container can change. Usage of experimental flavor is at users risk.
 280
 281 Stable `barometer-collectd` container is intended for work in production
 282 environment as it is based on latest collectd official release.
 283 `Barometer-collectd-master` and `barometer-collectd-experimental` containers
 284 can be used in order to try new collectd features.
 285 All flavors are located in `barometer` git repository - respective Dockerfiles
 286 are stored in subdirectories of `docker/` directory
 287
 288
 289 .. code:: bash
 290
 291     $ git clone https://gerrit.opnfv.org/gerrit/barometer
 292     $ ls barometer/docker|grep collectd
 293     barometer-collectd
 294     barometer-collectd-master
 295     barometer-collectd-experimental
 296
 297 .. note::
 298    Main directory of barometer source code (directory that contains 'docker',
 299    'docs', 'src' and systems sub-directories) will be referred as
 300    ``<BAROMETER_REPO_DIR>``
 301
 302 Download the collectd docker image
 303 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 304 If you wish to use a pre-built barometer image, you can pull the barometer
 305 image from https://hub.docker.com/r/opnfv/barometer-collectd/
 306
 307 .. code:: bash
 308
 309     $ docker pull opnfv/barometer-collectd
 310
 311 Build stable collectd container
 312 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 313
 314 .. code:: bash
 315
 316     $ cd <BAROMETER_REPO_DIR>/docker/barometer-collectd
 317     $ sudo docker build -t opnfv/barometer-collectd --build-arg http_proxy=`echo $http_proxy` \
 318       --build-arg https_proxy=`echo $https_proxy` --network=host -f Dockerfile .
 319
 320 .. note::
 321    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs to be
 322    passed only if system is behind an HTTP or HTTPS proxy server.
 323
 324 Check the docker images:
 325
 326 .. code:: bash
 327
 328    $ sudo docker images
 329
 330 Output should contain a barometer-collectd image:
 331
 332 .. code::
 333
 334    REPOSITORY                   TAG                 IMAGE ID            CREATED             SIZE
 335    opnfv/barometer-collectd     latest              05f2a3edd96b        3 hours ago         1.2GB
 336    centos                       7                   196e0ce0c9fb        4 weeks ago         197MB
 337    centos                       latest              196e0ce0c9fb        4 weeks ago         197MB
 338    hello-world                  latest              05a3bd381fc2        4 weeks ago         1.84kB
 339
 340 .. note::
 341    If you do not plan to use collectd-master and collectd-experimental barometer
 342    containers, then you can proceed directly to section `Run the collectd stable docker image`_
 343
 344
 345 Build collectd-master container
 346 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 347
 348 .. code:: bash
 349
 350     $ cd <BAROMETER_REPO_DIR>
 351     $ sudo docker build -t opnfv/barometer-collectd-master \
 352      --build-arg http_proxy=`echo $http_proxy` \
 353      --build-arg https_proxy=`echo $https_proxy` --network=host -f \
 354      docker/barometer-collectd-master/Dockerfile .
 355
 356 .. note::
 357    For `barometer-collectd-master` and `barometer-collectd-experimental` containers
 358    proxy parameters should be passed only if system is behind an HTTP or HTTPS
 359    proxy server (same as for stable collectd container)
 360
 361 Build collectd-experimental container
 362 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 363
 364 .. code:: bash
 365
 366     $ cd <BAROMETER_REPO_DIR>
 367     $ sudo docker build -t opnfv/barometer-collectd-experimental \
 368      --build-arg http_proxy=`echo $http_proxy` \
 369      --build-arg https_proxy=`echo $https_proxy` \
 370      --network=host -f docker/barometer-collectd-experimental/Dockerfile .
 371
 372 .. note::
 373    For `barometer-collectd-master` and `barometer-collectd-experimental` containers
 374    proxy parameters should be passed only if system is behind an HTTP or HTTPS
 375    proxy server (same as for stable collectd container)
 376
 377 Run the collectd stable docker image
 378 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 379 .. code:: bash
 380
 381    $ cd <BAROMETER_REPO_DIR>
 382    $ sudo docker run -ti --net=host -v \
 383    `pwd`/src/collectd/collectd_sample_configs:/opt/collectd/etc/collectd.conf.d \
 384    -v /var/run:/var/run -v /tmp:/tmp -v /sys/fs/resctrl:/sys/fs/resctrl \
 385    --privileged opnfv/barometer-collectd
 386
 387 .. note::
 388    The docker collectd image contains configuration for all the collectd
 389    plugins. In the command above we are overriding
 390    /opt/collectd/etc/collectd.conf.d by mounting a host directory
 391    src/collectd/collectd_sample_configs that contains only the sample
 392    configurations we are interested in running.
 393
 394    *If some dependencies for plugins listed in configuration directory
 395    aren't met, then collectd startup may fail(collectd tries to
 396    initialize plugins configurations for all given config files that can
 397    be found in shared configs directory and may fail if some dependency
 398    is missing).*
 399
 400    If `DPDK` or `RDT` can't be installed on host, then corresponding config
 401    files should be removed from shared configuration directory
 402    (`<BAROMETER_REPO_DIR>/src/collectd/collectd_sample_configs/`) prior
 403    to starting barometer-collectd container. By example: in case of missing
 404    `DPDK` functionality on the host, `dpdkstat.conf` and `dpdkevents.conf`
 405    should be removed.
 406
 407    Sample configurations can be found at:
 408    https://github.com/opnfv/barometer/tree/master/src/collectd/collectd_sample_configs
 409
 410    List of barometer-collectd dependencies on host for various plugins
 411    can be found at:
 412    https://wiki.opnfv.org/display/fastpath/Barometer-collectd+host+dependencies
 413
 414    The Resource Control file system (/sys/fs/resctrl) can be bound from host to
 415    container only if this directory exists on the host system. Otherwise omit
 416    the '-v /sys/fs/resctrl:/sys/fs/resctrl' part in docker run command.
 417    More information about resctrl can be found at:
 418    https://github.com/intel/intel-cmt-cat/wiki/resctrl
 419
 420 Check your docker image is running
 421
 422 .. code:: bash
 423
 424    sudo docker ps
 425
 426 To make some changes when the container is running run:
 427
 428 .. code:: bash
 429
 430    sudo docker exec -ti <CONTAINER ID> /bin/bash
 431
 432 Run the barometer-collectd-master docker image
 433 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 434 Run command for `barometer-collectd-master` container is very similar to command
 435 used for stable container - the only differences are name of the image
 436 and location of the sample configuration files(as different version of collectd
 437 plugins requiring different configuration files)
 438
 439
 440 .. code:: bash
 441
 442    $ cd <BAROMETER_REPO_DIR>
 443    $ sudo docker run -ti --net=host -v \
 444    `pwd`/src/collectd/collectd_sample_configs-master:/opt/collectd/etc/collectd.conf.d \
 445    -v /var/run:/var/run -v /tmp:/tmp -v /sys/fs/resctrl:/sys/fs/resctrl \
 446    --privileged opnfv/barometer-collectd-master
 447
 448 .. note::
 449    Barometer collectd docker images are sharing some directories with host
 450    (e.g. /tmp) therefore only one of collectd barometer flavors can be run
 451    at a time. In other words, if you want to try `barometer-collectd-master` or
 452    `barometer-collectd-experimental` image, please stop instance of
 453    `barometer-collectd(stable)` image first.
 454
 455    The Resource Control file system (/sys/fs/resctrl) can be bound from host to
 456    container only if this directory exists on the host system. Otherwise omit
 457    the '-v /sys/fs/resctrl:/sys/fs/resctrl' part in docker run command.
 458    More information about resctrl can be found at:
 459    https://github.com/intel/intel-cmt-cat/wiki/resctrl
 460
 461 Run the barometer-collectd-experimental docker image
 462 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 463 Barometer-collectd-experimental container shares default configuration files
 464 with 'barometer-collectd-master' equivalent but some of experimental pull
 465 requests may require modified configuration. Additional configuration files that
 466 are required specifically by experimental container can be found in
 467 `docker/barometer-collectd-experimental/experimental-configs/`
 468 directory. Content of this directory (all \*.conf files) should be copied to
 469 `src/collectd/collectd_sample_configs-master` directory before first run of
 470 experimental container.
 471
 472 .. code:: bash
 473
 474    $ cd <BAROMETER_REPO_DIR>
 475    $ cp docker/barometer-collectd-experimental/experimental-configs/*.conf \
 476      src/collectd/collectd_sample_configs-master
 477
 478 When configuration files are up to date for experimental container, it can be
 479 launched using following command (almost identical to run-command for 'master'
 480 collectd container)
 481
 482 .. code:: bash
 483
 484    $ cd <BAROMETER_REPO_DIR>
 485    $ sudo docker run -ti --net=host -v \
 486    `pwd`/src/collectd/collectd_sample_configs-master:/opt/collectd/etc/collectd.conf.d \
 487    -v /var/run:/var/run -v /tmp:/tmp -v /sys/fs/resctrl:/sys/fs/resctrl --privileged \
 488    opnfv/barometer-collectd-experimental
 489
 490 .. note::
 491    The Resource Control file system (/sys/fs/resctrl) can be bound from host to
 492    container only if this directory exists on the host system. Otherwise omit
 493    the '-v /sys/fs/resctrl:/sys/fs/resctrl' part in docker run command.
 494    More information about resctrl can be found at:
 495    https://github.com/intel/intel-cmt-cat/wiki/resctrl
 496
 497
 498 Build and Run InfluxDB and Grafana docker images
 499 ------------------------------------------------
 500
 501 Overview
 502 ^^^^^^^^
 503 The barometer-influxdb image is based on the influxdb:1.3.7 image from the influxdb dockerhub. To
 504 view detils on the base image please visit
 505 `https://hub.docker.com/_/influxdb/  <https://hub.docker.com/_/influxdb/>`_ Page includes details of
 506 exposed ports and configurable enviromental variables of the base image.
 507
 508 The barometer-grafana image is based on grafana:4.6.3 image from the grafana dockerhub. To view
 509 details on the base image please visit
 510 `https://hub.docker.com/r/grafana/grafana/ <https://hub.docker.com/r/grafana/grafana/>`_ Page
 511 includes details on exposed ports and configurable enviromental variables of the base image.
 512
 513 The barometer-grafana image includes pre-configured source and dashboards to display statistics exposed
 514 by the barometer-collectd image. The default datasource is an influxdb database running on localhost
 515 but the address of the influxdb server can be modified when launching the image by setting the
 516 environmental variables influxdb_host to IP or hostname of host on which influxdb server is running.
 517
 518 Additional dashboards can be added to barometer-grafana by mapping a volume to /opt/grafana/dashboards.
 519 Incase where a folder is mounted to this volume only files included in this folder will be visible
 520 inside barometer-grafana. To ensure all default files are also loaded please ensure they are included in
 521 volume folder been mounted. Appropriate example are given in section `Run the Grafana docker image`_
 522
 523 Download the InfluxDB and Grafana docker images
 524 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 525 If you wish to use pre-built barometer project's influxdb and grafana images, you can pull the
 526 images from https://hub.docker.com/r/opnfv/barometer-influxdb/ and https://hub.docker.com/r/opnfv/barometer-grafana/
 527
 528 .. note::
 529    If your preference is to build images locally please see sections `Build InfluxDB Docker Image`_ and
 530    `Build Grafana Docker Image`_
 531
 532 .. code:: bash
 533
 534     $ docker pull opnfv/barometer-influxdb
 535     $ docker pull opnfv/barometer-grafana
 536
 537 .. note::
 538    If you have pulled the pre-built barometer-influxdb and barometer-grafana images there is no
 539    requirement to complete steps outlined in  sections `Build InfluxDB Docker Image`_ and
 540    `Build Grafana Docker Image`_ and you can proceed directly to section
 541    `Run the Influxdb and Grafana Images`_
 542
 543 Build InfluxDB docker image
 544 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 545
 546 Build influxdb image from Dockerfile
 547
 548 .. code:: bash
 549
 550   $ cd barometer/docker/barometer-influxdb
 551   $ sudo docker build -t opnfv/barometer-influxdb --build-arg http_proxy=`echo $http_proxy` \
 552     --build-arg https_proxy=`echo $https_proxy` --network=host -f Dockerfile .
 553
 554 .. note::
 555    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs to
 556    be passed only if system is behind an HTTP or HTTPS proxy server.
 557
 558 Check the docker images:
 559
 560 .. code:: bash
 561
 562    $ sudo docker images
 563
 564 Output should contain an influxdb image:
 565
 566 .. code::
 567
 568    REPOSITORY                   TAG                 IMAGE ID            CREATED            SIZE
 569    opnfv/barometer-influxdb     latest              1e4623a59fe5        3 days ago         191MB
 570
 571 Build Grafana docker image
 572 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 573
 574 Build Grafana image from Dockerfile
 575
 576 .. code:: bash
 577
 578   $ cd barometer/docker/barometer-grafana
 579   $ sudo docker build -t opnfv/barometer-grafana --build-arg http_proxy=`echo $http_proxy` \
 580     --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
 581
 582 .. note::
 583    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs to
 584    be passed only if system is behind an HTTP or HTTPS proxy server.
 585
 586 Check the docker images:
 587
 588 .. code:: bash
 589
 590    $ sudo docker images
 591
 592 Output should contain an influxdb image:
 593
 594 .. code::
 595
 596    REPOSITORY                   TAG                 IMAGE ID            CREATED             SIZE
 597    opnfv/barometer-grafana      latest              05f2a3edd96b        3 hours ago         1.2GB
 598
 599 Run the Influxdb and Grafana Images
 600 -----------------------------------
 601
 602 Run the InfluxDB docker image
 603 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 604 .. code:: bash
 605
 606    $ sudo docker run -tid -v /var/lib/influxdb:/var/lib/influxdb --net=host\
 607     --name bar-influxdb opnfv/barometer-influxdb
 608
 609 Check your docker image is running
 610
 611 .. code:: bash
 612
 613    sudo docker ps
 614
 615 To make some changes when the container is running run:
 616
 617 .. code:: bash
 618
 619    sudo docker exec -ti <CONTAINER ID> /bin/bash
 620
 621 When both collectd and InfluxDB containers are located
 622 on the same host, then no additional configuration have to be added and you
 623 can proceed directly to `Run the Grafana docker image`_ section.
 624
 625 Modify collectd to support InfluxDB on another host
 626 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 627 If InfluxDB and collectd containers are located on separate hosts, then
 628 additional configuration have to be done in ``collectd`` container - it
 629 normally sends data using network plugin to 'localhost/127.0.0.1' therefore
 630 changing output location is required:
 631
 632 1. Stop and remove running bar-collectd container (if it is running)
 633
 634    .. code:: bash
 635
 636       $ sudo docker ps #to get collectd container name
 637       $ sudo docker rm -f <COLLECTD_CONTAINER_NAME>
 638
 639 2. Go to location where shared collectd config files are stored
 640
 641    .. code:: bash
 642
 643       $ cd <BAROMETER_REPO_DIR>
 644       $ cd src/collectd/collectd_sample_configs
 645
 646 3. Edit content of ``network.conf`` file.
 647    By default this file looks like that:
 648
 649    .. code::
 650
 651       LoadPlugin  network
 652       <Plugin network>
 653       Server "127.0.0.1" "25826"
 654       </Plugin>
 655
 656    ``127.0.0.1`` string has to be replaced with the IP address of host where
 657    InfluxDB container is running (e.g. ``192.168.121.111``). Edit this using your
 658    favorite text editor.
 659
 660 4. Start again collectd container like it is described in
 661    `Run the collectd stable docker image`_ chapter
 662
 663    .. code:: bash
 664
 665       $ cd <BAROMETER_REPO_DIR>
 666       $ sudo docker run -ti --name bar-collectd --net=host -v \
 667       `pwd`/src/collectd/collectd_sample_configs:/opt/collectd/etc/collectd.conf.d \
 668       -v /var/run:/var/run -v /tmp:/tmp --privileged opnfv/barometer-collectd
 669
 670 Now collectd container will be sending data to InfluxDB container located on
 671 remote Host pointed by IP configured in step 3.
 672
 673 Run the Grafana docker image
 674 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 675
 676 Connecting to an influxdb instance running on local system and adding own custom dashboards
 677
 678 .. code:: bash
 679
 680    $ cd <BAROMETER_REPO_DIR>
 681    $ sudo docker run -tid -v /var/lib/grafana:/var/lib/grafana \
 682      -v ${PWD}/docker/barometer-grafana/dashboards:/opt/grafana/dashboards \
 683      --name bar-grafana --net=host opnfv/barometer-grafana
 684
 685 Connecting to an influxdb instance running on remote system with hostname of someserver and IP address
 686 of 192.168.121.111
 687
 688 .. code:: bash
 689
 690    $ sudo docker run -tid -v /var/lib/grafana:/var/lib/grafana --net=host -e \
 691      influxdb_host=someserver --add-host someserver:192.168.121.111 --name \
 692      bar-grafana opnfv/barometer-grafana
 693
 694 Check your docker image is running
 695
 696 .. code:: bash
 697
 698    sudo docker ps
 699
 700 To make some changes when the container is running run:
 701
 702 .. code:: bash
 703
 704    sudo docker exec -ti <CONTAINER ID> /bin/bash
 705
 706 Connect to <host_ip>:3000 with a browser and log into grafana: admin/admin
 707
 708 Cleanup of influxdb/grafana configuration
 709 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 710
 711 When user wants to remove current grafana and influxdb configuration,
 712 folowing actions have to be performed
 713
 714 1. Stop and remove running influxdb and grafana containers
 715
 716 .. code:: bash
 717
 718    sudo docker rm -f bar-grafana bar-influxdb
 719
 720 2. Remove shared influxdb and grafana folders from the Host
 721
 722 .. code:: bash
 723
 724    sudo rm -rf /var/lib/grafana
 725    sudo rm -rf /var/lib/influxdb
 726
 727 .. note::
 728    Shared folders are storing configuration of grafana and influxdb
 729    containers. In case of changing influxdb or grafana configuration
 730    (e.g. moving influxdb to another host) it is good to perform cleanup
 731    on shared folders to not affect new setup with an old configuration.
 732
 733 Build and Run VES and Kafka Docker Images
 734 -----------------------------------------
 735
 736 Download VES and Kafka docker images
 737 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 738
 739 If you wish to use pre-built barometer project's VES and kafka images, you can pull the
 740 images from https://hub.docker.com/r/opnfv/barometer-ves/ and  https://hub.docker.com/r/opnfv/barometer-kafka/
 741
 742 .. note::
 743    If your preference is to build images locally please see sections `Build the Kafka Image`_ and
 744    `Build VES Image`_
 745
 746 .. code:: bash
 747
 748     $ docker pull opnfv/barometer-kafka
 749     $ docker pull opnfv/barometer-ves
 750
 751 .. note::
 752    If you have pulled the pre-built images there is no requirement to complete steps outlined
 753    in sections `Build Kafka Docker Image`_ and `Build VES Docker Image`_ and you can proceed directly to section
 754    `Run Kafka Docker Image`_
 755
 756 Build Kafka docker image
 757 ^^^^^^^^^^^^^^^^^^^^^^^^
 758
 759 Build Kafka docker image:
 760
 761 .. code:: bash
 762
 763     $ cd barometer/docker/barometer-kafka
 764     $ sudo docker build -t opnfv/barometer-kafka --build-arg http_proxy=`echo $http_proxy` \
 765       --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
 766
 767 .. note::
 768    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs
 769    to be passed only if system is behind an HTTP or HTTPS proxy server.
 770
 771 Check the docker images:
 772
 773 .. code:: bash
 774
 775    $ sudo docker images
 776
 777 Output should contain a barometer image:
 778
 779 .. code::
 780
 781    REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
 782    opnfv/barometer-kafka     latest              05f2a3edd96b        3 hours ago         1.2GB
 783
 784 Build VES docker image
 785 ^^^^^^^^^^^^^^^^^^^^^^
 786
 787 Build VES application docker image:
 788
 789 .. code:: bash
 790
 791     $ cd barometer/docker/barometer-ves
 792     $ sudo docker build -t opnfv/barometer-ves --build-arg http_proxy=`echo $http_proxy` \
 793       --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
 794
 795 .. note::
 796    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs
 797    to be passed only if system is behind an HTTP or HTTPS proxy server.
 798
 799 Check the docker images:
 800
 801 .. code:: bash
 802
 803    $ sudo docker images
 804
 805 Output should contain a barometer image:
 806
 807 .. code::
 808
 809    REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
 810    opnfv/barometer-ves       latest              05f2a3edd96b        3 hours ago         1.2GB
 811
 812 Run Kafka docker image
 813 ^^^^^^^^^^^^^^^^^^^^^^
 814
 815 .. note::
 816    Before running Kafka an instance of Zookeeper must be running for the Kafka broker to register
 817    with. Zookeeper can be running locally or on a remote platform. Kafka's broker_id and address of
 818    its zookeeper instance can be configured by setting values for environmental variables 'broker_id'
 819    and 'zookeeper_node'. In instance where 'broker_id' and/or 'zookeeper_node' is not set the default
 820    setting of broker_id=0 and zookeeper_node=localhost is used. In intance where Zookeeper is running
 821    on same node as Kafka and there is a one to one relationship between Zookeeper and Kafka, default
 822    setting can be used. The docker argument `add-host` adds hostname and IP address to
 823    /etc/hosts file in container
 824
 825 Run zookeeper docker image:
 826
 827 .. code:: bash
 828
 829    $ sudo docker run -tid --net=host -p 2181:2181 zookeeper:3.4.11
 830
 831 Run kafka docker image which connects with a zookeeper instance running on same node with a 1:1 relationship
 832
 833 .. code:: bash
 834
 835    $ sudo docker run -tid --net=host -p 9092:9092 opnfv/barometer-kafka
 836
 837
 838 Run kafka docker image which connects with a zookeeper instance running on a node with IP address of
 839 192.168.121.111 using broker ID of 1
 840
 841 .. code:: bash
 842
 843    $ sudo docker run -tid --net=host -p 9092:9092 --env broker_id=1 --env zookeeper_node=zookeeper --add-host \
 844      zookeeper:192.168.121.111 opnfv/barometer-kafka
 845
 846 Run VES Application docker image
 847 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 848 .. note::
 849    VES application uses configuration file ves_app_config.conf from directory
 850    barometer/3rd_party/collectd-ves-app/ves_app/config/ and host.yaml file from
 851    barometer/3rd_party/collectd-ves-app/ves_app/yaml/ by default. If you wish to use a custom config
 852    file it should be mounted to mount point /opt/ves/config/ves_app_config.conf. To use an alternative yaml
 853    file from folder barometer/3rd_party/collectd-ves-app/ves_app/yaml the name of the yaml file to use
 854    should be passed as an additional command. If you wish to use a custom file the file should be
 855    mounted to mount point /opt/ves/yaml/ Please see examples below
 856
 857 Run VES docker image with default configuration
 858
 859 .. code:: bash
 860
 861    $ sudo docker run -tid --net=host opnfv/barometer-ves
 862
 863 Run VES docker image with guest.yaml files from barometer/3rd_party/collectd-ves-app/ves_app/yaml/
 864
 865 .. code:: bash
 866
 867    $ sudo docker run -tid --net=host opnfv/barometer-ves guest.yaml
 868
 869
 870 Run VES docker image with using custom config and yaml files. In example below yaml/ folder cotains
 871 file named custom.yaml
 872
 873 .. code:: bash
 874
 875    $ sudo docker run -tid --net=host -v ${PWD}/custom.config:/opt/ves/config/ves_app_config.conf \
 876      -v ${PWD}/yaml/:/opt/ves/yaml/ opnfv/barometer-ves custom.yaml
 877
 878 Run VES Test Collector application
 879 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 880
 881 VES Test Collector application can be used for displaying platform
 882 wide metrics that are collected by barometer-ves container.
 883 Setup instructions are located in: :ref:`Setup VES Test Collector`
 884
 885 Build and Run DMA and Redis Docker Images
 886 -----------------------------------------
 887
 888 Download DMA docker images
 889 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 890
 891 If you wish to use pre-built barometer project's DMA images, you can pull the
 892 images from https://hub.docker.com/r/opnfv/barometer-dma/
 893
 894 .. note::
 895    If your preference is to build images locally please see sections `Build DMA Docker Image`_
 896
 897 .. code:: bash
 898
 899     $ docker pull opnfv/barometer-dma
 900
 901 .. note::
 902    If you have pulled the pre-built images there is no requirement to complete steps outlined
 903    in sections `Build DMA Docker Image`_ and you can proceed directly to section
 904    `Run DMA Docker Image`_
 905
 906 Build DMA docker image
 907 ^^^^^^^^^^^^^^^^^^^^^^
 908
 909 Build DMA docker image:
 910
 911 .. code:: bash
 912
 913     $ cd barometer/docker/barometer-dma
 914     $ sudo docker build -t opnfv/barometer-dma --build-arg http_proxy=`echo $http_proxy` \
 915       --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
 916
 917 .. note::
 918    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs
 919    to be passed only if system is behind an HTTP or HTTPS proxy server.
 920
 921 Check the docker images:
 922
 923 .. code:: bash
 924
 925    $ sudo docker images
 926
 927 Output should contain a barometer image:
 928
 929 .. code::
 930
 931    REPOSITORY                   TAG                 IMAGE ID            CREATED             SIZE
 932    opnfv/barometer-dma          latest              2f14fbdbd498        3 hours ago         941 MB
 933
 934 Run Redis docker image
 935 ^^^^^^^^^^^^^^^^^^^^^^
 936
 937 .. note::
 938    Before running DMA, Redis must be running.
 939
 940 Run Redis docker image:
 941
 942 .. code:: bash
 943
 944    $ sudo docker run -tid -p 6379:6379 --name barometer-redis redis
 945
 946 Check your docker image is running
 947
 948 .. code:: bash
 949
 950    sudo docker ps
 951
 952 Run DMA docker image
 953 ^^^^^^^^^^^^^^^^^^^^
 954 .. note::
 955
 956 Run DMA docker image with default configuration
 957
 958 .. code:: bash
 959
 960    $ cd barometer/docker/barometer-dma
 961    $ sudo mkdir /etc/barometer-dma
 962    $ sudo cp ../../src/dma/examples/config.toml /etc/barometer-dma/
 963    $ sudo vi /etc/barometer-dma/config.toml
 964    (edit amqp_password and os_password:OpenStack admin password)
 965
 966    $ sudo su -
 967    (When there is no key for SSH access authentication)
 968    # ssh-keygen
 969    (Press Enter until done)
 970    (Backup if necessary)
 971    # cp ~/.ssh/authorized_keys ~/.ssh/authorized_keys_org
 972    # cat ~/.ssh/authorized_keys_org ~/.ssh/id_rsa.pub \
 973      > ~/.ssh/authorized_keys
 974    # exit
 975
 976    $ sudo docker run -tid --net=host --name server \
 977      -v /etc/barometer-dma:/etc/barometer-dma \
 978      -v /root/.ssh/id_rsa:/root/.ssh/id_rsa \
 979      -v /etc/collectd/collectd.conf.d:/etc/collectd/collectd.conf.d \
 980      opnfv/barometer-dma /server
 981
 982    $ sudo docker run -tid --net=host --name infofetch \
 983      -v /etc/barometer-dma:/etc/barometer-dma \
 984      -v /var/run/libvirt:/var/run/libvirt \
 985      opnfv/barometer-dma /infofetch
 986
 987    (Execute when installing the threshold evaluation binary)
 988    $ sudo docker cp infofetch:/threshold ./
 989    $ sudo ln -s ${PWD}/threshold /usr/local/bin/
 990
 991 References
 992 ^^^^^^^^^^
 993 .. [1] https://docs.docker.com/config/daemon/systemd/#httphttps-proxy
 994 .. [2] https://docs.docker.com/engine/install/centos/#install-using-the-repository
 995 .. [3] https://docs.docker.com/engine/userguide/
 996
 997