docs/release/userguide/docker.userguide.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 User 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 Barometer Docker Images Description
  35 -----------------------------------
  36
  37 .. Describe the specific features and how it is realised in the scenario in a brief manner
  38 .. to ensure the user understand the context for the user guide instructions to follow.
  39
  40 Barometer Collectd Image
  41 ^^^^^^^^^^^^^^^^^^^^^^^^
  42 The barometer collectd docker image gives you a collectd installation that includes all
  43 the barometer plugins.
  44
  45 .. note::
  46    The Dockerfile is available in the docker/barometer-collectd directory in the barometer repo.
  47    The Dockerfile builds a CentOS 7 docker image.
  48    The container MUST be run as a privileged container.
  49
  50 Collectd is a daemon which collects system performance statistics periodically
  51 and provides a variety of mechanisms to publish the collected metrics. It
  52 supports more than 90 different input and output plugins. Input plugins
  53 retrieve metrics and publish them to the collectd deamon, while output plugins
  54 publish the data they receive to an end point. Collectd also has infrastructure
  55 to support thresholding and notification.
  56
  57 Collectd docker image has enabled the following collectd plugins (in addition
  58 to the standard collectd plugins):
  59
  60 * hugepages plugin
  61 * Open vSwitch events Plugin
  62 * Open vSwitch stats Plugin
  63 * mcelog plugin
  64 * PMU plugin
  65 * RDT plugin
  66 * virt
  67 * SNMP Agent
  68 * Kafka_write plugin
  69
  70 Plugins and third party applications in Barometer repository that will be available in the
  71 docker image:
  72
  73 * Open vSwitch PMD stats
  74 * ONAP VES application
  75 * gnocchi plugin
  76 * aodh plugin
  77 * Legacy/IPMI
  78
  79 InfluxDB + Grafana Docker Images
  80 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  81
  82 The Barometer project's InfluxDB and Grafana docker images are 2 docker images that database and graph
  83 statistics reported by the Barometer collectd docker. InfluxDB is an open-source time series database
  84 tool which stores the data from collectd for future analysis via Grafana, which is a open-source
  85 metrics anlytics and visualisation suite which can be accessed through any browser.
  86
  87 VES + Kafka Docker Images
  88 ^^^^^^^^^^^^^^^^^^^^^^^^^
  89
  90 The Barometer project's VES application and Kafka docker images are based on a CentOS 7 image. Kafka
  91 docker image has a dependancy on `Zookeeper <https://zookeeper.apache.org/>`_. Kafka must be able to
  92 connect and register with an instance of Zookeeper that is either running on local or remote host.
  93 Kafka recieves and stores metrics recieved from Collectd. VES application pulls latest metrics from Kafka
  94 which it normalizes into VES format for sending to a VES collector. Please see details in
  95 :ref:`VES Application User Guide <barometer-ves-userguide>`
  96
  97 Installing Docker
  98 -----------------
  99 .. Describe the specific capabilities and usage for <XYZ> feature.
 100 .. Provide enough information that a user will be able to operate the feature on a deployed scenario.
 101
 102 On Ubuntu
 103 ^^^^^^^^^^
 104 .. note::
 105    * sudo permissions are required to install docker.
 106    * These instructions are for Ubuntu 16.10
 107
 108 To install docker:
 109
 110 .. code:: bash
 111
 112     $ sudo apt-get install curl
 113     $ sudo curl -fsSL https://get.docker.com/ | sh
 114     $ sudo usermod -aG docker <username>
 115     $ sudo systemctl status docker
 116
 117 Replace <username> above with an appropriate user name.
 118
 119 On CentOS
 120 ^^^^^^^^^^
 121 .. note::
 122    * sudo permissions are required to install docker.
 123    * These instructions are for CentOS 7
 124
 125 To install docker:
 126
 127 .. code:: bash
 128
 129     $ sudo yum remove docker docker-common docker-selinux docker-engine
 130     $ sudo yum install -y yum-utils  device-mapper-persistent-data  lvm2
 131     $ sudo yum-config-manager   --add-repo    https://download.docker.com/linux/centos/docker-ce.repo
 132     $ sudo yum-config-manager --enable docker-ce-edge
 133     $ sudo yum-config-manager --enable docker-ce-test
 134     $ sudo yum install docker-ce
 135     $ sudo usermod -aG docker <username>
 136     $ sudo systemctl status docker
 137
 138 Replace <username> above with an appropriate user name.
 139
 140 .. note::
 141    If this is the first time you are installing a package from a recently added
 142    repository, you will be prompted to accept the GPG key, and the key’s
 143    fingerprint will be shown. Verify that the fingerprint is correct, and if so,
 144    accept the key. The fingerprint should match060A 61C5 1B55 8A7F 742B 77AA C52F
 145    EB6B 621E 9F35.
 146
 147         Retrieving key from https://download.docker.com/linux/centos/gpg
 148         Importing GPG key 0x621E9F35:
 149          Userid     : "Docker Release (CE rpm) <docker@docker.com>"
 150          Fingerprint: 060a 61c5 1b55 8a7f 742b 77aa c52f eb6b 621e 9f35
 151          From       : https://download.docker.com/linux/centos/gpg
 152         Is this ok [y/N]: y
 153
 154 Proxy Configuration:
 155 ^^^^^^^^^^^^^^^^^^^^
 156 .. note::
 157    This applies for both CentOS and Ubuntu.
 158
 159 If you are behind an HTTP or HTTPS proxy server, you will need to add this
 160 configuration in the Docker systemd service file.
 161
 162 1. Create a systemd drop-in directory for the docker service:
 163
 164 .. code:: bash
 165
 166    $ sudo mkdir -p /etc/systemd/system/docker.service.d
 167
 168 2. Create a file
 169 called /etc/systemd/system/docker.service.d/http-proxy.conf that adds
 170 the HTTP_PROXY environment variable:
 171
 172 .. code:: bash
 173
 174    [Service]
 175    Environment="HTTP_PROXY=http://proxy.example.com:80/"
 176
 177 Or, if you are behind an HTTPS proxy server, create a file
 178 called /etc/systemd/system/docker.service.d/https-proxy.conf that adds
 179 the HTTPS_PROXY environment variable:
 180
 181 .. code:: bash
 182
 183     [Service]
 184     Environment="HTTPS_PROXY=https://proxy.example.com:443/"
 185
 186 Or create a single file with all the proxy configurations:
 187 /etc/systemd/system/docker.service.d/proxy.conf
 188
 189 .. code:: bash
 190
 191     [Service]
 192     Environment="HTTP_PROXY=http://proxy.example.com:80/"
 193     Environment="HTTPS_PROXY=https://proxy.example.com:443/"
 194     Environment="FTP_PROXY=ftp://proxy.example.com:443/"
 195     Environment="NO_PROXY=localhost"
 196
 197 3. Flush changes:
 198
 199 .. code:: bash
 200
 201     $ sudo systemctl daemon-reload
 202
 203 4. Restart Docker:
 204
 205 .. code:: bash
 206
 207     $ sudo systemctl restart docker
 208
 209 5. Check docker environment variables:
 210
 211 .. code:: bash
 212
 213     sudo systemctl show --property=Environment docker
 214
 215 Test docker installation
 216 ^^^^^^^^^^^^^^^^^^^^^^^^
 217 .. note::
 218    This applies for both CentOS and Ubuntu.
 219
 220 .. code:: bash
 221
 222    $ sudo docker run hello-world
 223
 224 The output should be something like:
 225
 226 .. code:: bash
 227
 228    Unable to find image 'hello-world:latest' locally
 229    latest: Pulling from library/hello-world
 230    5b0f327be733: Pull complete
 231    Digest: sha256:07d5f7800dfe37b8c2196c7b1c524c33808ce2e0f74e7aa00e603295ca9a0972
 232    Status: Downloaded newer image for hello-world:latest
 233
 234    Hello from Docker!
 235    This message shows that your installation appears to be working correctly.
 236
 237    To generate this message, Docker took the following steps:
 238     1. The Docker client contacted the Docker daemon.
 239     2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
 240     3. The Docker daemon created a new container from that image which runs the
 241        executable that produces the output you are currently reading.
 242     4. The Docker daemon streamed that output to the Docker client, which sent it
 243        to your terminal.
 244
 245 To try something more ambitious, you can run an Ubuntu container with:
 246
 247 .. code:: bash
 248
 249     $ docker run -it ubuntu bash
 250
 251 Build and Run Collectd Docker Image
 252 -----------------------------------
 253
 254 Download the collectd docker image
 255 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 256 If you wish to use a pre-built barometer image, you can pull the barometer
 257 image from https://hub.docker.com/r/opnfv/barometer-collectd/
 258
 259 .. code:: bash
 260
 261     $ docker pull opnfv/barometer-collectd
 262
 263 Build the collectd docker image
 264 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 265
 266 .. code:: bash
 267
 268     $ git clone https://gerrit.opnfv.org/gerrit/barometer
 269     $ cd barometer/docker/barometer-collectd
 270     $ sudo docker build -t opnfv/barometer-collectd --build-arg http_proxy=`echo $http_proxy` \
 271       --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
 272
 273 .. note::
 274    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs to be
 275    passed only if system is behind an HTTP or HTTPS proxy server.
 276
 277 Check the docker images:
 278
 279 .. code:: bash
 280
 281    $ sudo docker images
 282
 283 Output should contain a barometer-collectd image:
 284
 285 .. code::
 286
 287    REPOSITORY                   TAG                 IMAGE ID            CREATED             SIZE
 288    opnfv/barometer-collectd     latest              05f2a3edd96b        3 hours ago         1.2GB
 289    centos                       7                   196e0ce0c9fb        4 weeks ago         197MB
 290    centos                       latest              196e0ce0c9fb        4 weeks ago         197MB
 291    hello-world                  latest              05a3bd381fc2        4 weeks ago         1.84kB
 292
 293 Run the collectd docker image
 294 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 295 .. code:: bash
 296
 297    $ sudo docker run -tid --net=host -v `pwd`/../src/collectd_sample_configs:/opt/collectd/etc/collectd.conf.d \
 298     -v /var/run:/var/run -v /tmp:/tmp --privileged opnfv/barometer-collectd /run_collectd.sh
 299
 300 .. note::
 301    The docker collectd image contains configuration for all the collectd plugins. In the command
 302    above we are overriding /opt/collectd/etc/collectd.conf.d by mounting a host directory
 303    `pwd`/../src/collectd_sample_configs that contains only the sample configurations we are interested
 304    in running. *It's important to do this if you don't have DPDK, or RDT installed on the host*.
 305    Sample configurations can be found at:
 306    https://github.com/opnfv/barometer/tree/master/src/collectd/collectd_sample_configs
 307
 308 Check your docker image is running
 309
 310 .. code:: bash
 311
 312    sudo docker ps
 313
 314 To make some changes when the container is running run:
 315
 316 .. code:: bash
 317
 318    sudo docker exec -ti <CONTAINER ID> /bin/bash
 319
 320 Build and Run InfluxDB and Grafana docker images
 321 ------------------------------------------------
 322
 323 Overview
 324 ^^^^^^^^
 325 The barometer-influxdb image is based on the influxdb:1.3.7 image from the influxdb dockerhub. To
 326 view detils on the base image please visit
 327 `https://hub.docker.com/_/influxdb/  <https://hub.docker.com/_/influxdb/>`_ Page includes details of
 328 exposed ports and configurable enviromental variables of the base image.
 329
 330 The barometer-grafana image is based on grafana:4.6.3 image from the grafana dockerhub. To view
 331 details on the base image please visit
 332 `https://hub.docker.com/r/grafana/grafana/ <https://hub.docker.com/r/grafana/grafana/>`_ Page
 333 includes details on exposed ports and configurable enviromental variables of the base image.
 334
 335 The barometer-grafana image includes pre-configured source and dashboards to display statistics exposed
 336 by the barometer-collectd image. The default datasource is an influxdb database running on localhost
 337 but the address of the influxdb server can be modified when launching the image by setting the
 338 environmental variables influxdb_host to IP or hostname of host on which influxdb server is running.
 339
 340 Additional dashboards can be added to barometer-grafana by mapping a volume to /opt/grafana/dashboards.
 341 Incase where a folder is mounted to this volume only files included in this folder will be visible
 342 inside barometer-grafana. To ensure all default files are also loaded please ensure they are included in
 343 volume folder been mounted. Appropriate example are given in section `Run the Grafana docker image`_
 344
 345 Download the InfluxDB and Grafana docker images
 346 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 347 If you wish to use pre-built barometer project's influxdb and grafana images, you can pull the
 348 images from https://hub.docker.com/r/opnfv/barometer-influxdb/ and https://hub.docker.com/r/opnfv/barometer-grafana/
 349
 350 .. note::
 351    If your preference is to build images locally please see sections `Build InfluxDB Docker Image`_ and
 352    `Build Grafana Docker Image`_
 353
 354 .. code:: bash
 355
 356     $ docker pull opnfv/barometer-influxdb
 357     $ docker pull opnfv/barometer-grafana
 358
 359 .. note::
 360    If you have pulled the pre-built barometer-influxdb and barometer-grafana images there is no
 361    requirement to complete steps outlined in  sections `Build InfluxDB Docker Image`_ and
 362    `Build Grafana Docker Image`_ and you can proceed directly to section
 363    `Run the Influxdb and Grafana Images`_ If you wish to run the barometer-influxdb and
 364    barometer-grafana images via Docker Compose proceed directly to section
 365    `Docker Compose`_.
 366
 367 Build InfluxDB docker image
 368 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 369
 370 Build influxdb image from Dockerfile
 371
 372 .. code:: bash
 373
 374   $ cd barometer/docker/barometer-influxdb
 375   $ sudo docker build -t opnfv/barometer-influxdb --build-arg http_proxy=`echo $http_proxy` \
 376     --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
 377
 378 .. note::
 379    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs to
 380    be passed only if system is behind an HTTP or HTTPS proxy server.
 381
 382 Check the docker images:
 383
 384 .. code:: bash
 385
 386    $ sudo docker images
 387
 388 Output should contain an influxdb image:
 389
 390 .. code::
 391
 392    REPOSITORY                   TAG                 IMAGE ID            CREATED            SIZE
 393    opnfv/barometer-influxdb     latest              1e4623a59fe5        3 days ago         191MB
 394
 395 Build Grafana docker image
 396 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 397
 398 Build Grafana image from Dockerfile
 399
 400 .. code:: bash
 401
 402   $ cd barometer/docker/barometer-grafana
 403   $ sudo docker build -t opnfv/barometer-grafana --build-arg http_proxy=`echo $http_proxy` \
 404     --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
 405
 406 .. note::
 407    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs to
 408    be passed only if system is behind an HTTP or HTTPS proxy server.
 409
 410 Check the docker images:
 411
 412 .. code:: bash
 413
 414    $ sudo docker images
 415
 416 Output should contain an influxdb image:
 417
 418 .. code::
 419
 420    REPOSITORY                   TAG                 IMAGE ID            CREATED             SIZE
 421    opnfv/barometer-grafana      latest              05f2a3edd96b        3 hours ago         1.2GB
 422
 423 Run the Influxdb and Grafana Images
 424 -----------------------------------
 425
 426 Run the InfluxDB docker image
 427 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 428 .. code:: bash
 429
 430    $ sudo docker run -tid -v /var/lib/influxdb:/var/lib/influxdb -p 8086:8086 -p 25826:25826  opnfv/barometer-influxdb
 431
 432 Check your docker image is running
 433
 434 .. code:: bash
 435
 436    sudo docker ps
 437
 438 To make some changes when the container is running run:
 439
 440 .. code:: bash
 441
 442    sudo docker exec -ti <CONTAINER ID> /bin/bash
 443
 444 Run the Grafana docker image
 445 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 446
 447 Connecting to an influxdb instance running on local system and adding own custom dashboards
 448
 449 .. code:: bash
 450
 451    $ sudo docker run -tid -v /var/lib/grafana:/var/lib/grafana -v ${PWD}/dashboards:/opt/grafana/dashboards \
 452      -p 3000:3000 opnfv/barometer-grafana
 453
 454 Connecting to an influxdb instance running on remote system with hostname of someserver and IP address
 455 of 192.168.121.111
 456
 457 .. code:: bash
 458
 459    $ sudo docker run -tid -v /var/lib/grafana:/var/lib/grafana -p 3000:3000 -e \
 460      influxdb_host=someserver --add-host someserver:192.168.121.111 opnfv/barometer-grafana
 461
 462 Check your docker image is running
 463
 464 .. code:: bash
 465
 466    sudo docker ps
 467
 468 To make some changes when the container is running run:
 469
 470 .. code:: bash
 471
 472    sudo docker exec -ti <CONTAINER ID> /bin/bash
 473
 474 Connect to <host_ip>:3000 with a browser and log into grafana: admin/admin
 475
 476
 477 Build and Run VES and Kafka Docker Images
 478 ------------------------------------------
 479
 480 Download VES and Kafka docker images
 481 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 482
 483 If you wish to use pre-built barometer project's VES and kafka images, you can pull the
 484 images from https://hub.docker.com/r/opnfv/barometer-ves/ and  https://hub.docker.com/r/opnfv/barometer-kafka/
 485
 486 .. note::
 487    If your preference is to build images locally please see sections `Build the Kafka Image`_ and
 488    `Build VES Image`_
 489
 490 .. code:: bash
 491
 492     $ docker pull opnfv/barometer-kafka
 493     $ docker pull opnfv/barometer-ves
 494
 495 .. note::
 496    If you have pulled the pre-built images there is no requirement to complete steps outlined
 497    in sections `Build Kafka Docker Image`_ and `Build VES Docker Image`_ and you can proceed directly to section
 498    `Run Kafka Docker Image`_ If you wish to run the docker images via Docker Compose proceed directly to section `Docker Compose`_.
 499
 500 Build Kafka docker image
 501 ^^^^^^^^^^^^^^^^^^^^^^^^
 502
 503 Build Kafka docker image:
 504
 505 .. code:: bash
 506
 507     $ cd barometer/docker/barometer-kafka
 508     $ sudo docker build -t opnfv/barometer-kafka --build-arg http_proxy=`echo $http_proxy` \
 509       --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
 510
 511 .. note::
 512    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs
 513    to be passed only if system is behind an HTTP or HTTPS proxy server.
 514
 515 Check the docker images:
 516
 517 .. code:: bash
 518
 519    $ sudo docker images
 520
 521 Output should contain a barometer image:
 522
 523 .. code::
 524
 525    REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
 526    opnfv/barometer-kafka     latest              05f2a3edd96b        3 hours ago         1.2GB
 527
 528 Build VES docker image
 529 ^^^^^^^^^^^^^^^^^^^^^^
 530
 531 Build VES application docker image:
 532
 533 .. code:: bash
 534
 535     $ cd barometer/docker/barometer-ves
 536     $ sudo docker build -t opnfv/barometer-ves --build-arg http_proxy=`echo $http_proxy` \
 537       --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
 538
 539 .. note::
 540    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs
 541    to be passed only if system is behind an HTTP or HTTPS proxy server.
 542
 543 Check the docker images:
 544
 545 .. code:: bash
 546
 547    $ sudo docker images
 548
 549 Output should contain a barometer image:
 550
 551 .. code::
 552
 553    REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
 554    opnfv/barometer-ves       latest              05f2a3edd96b        3 hours ago         1.2GB
 555
 556 Run Kafka docker image
 557 ^^^^^^^^^^^^^^^^^^^^^^
 558
 559 .. note::
 560    Before running Kafka an instance of Zookeeper must be running for the Kafka broker to register
 561    with. Zookeeper can be running locally or on a remote platform. Kafka's broker_id and address of
 562    its zookeeper instance can be configured by setting values for environmental variables 'broker_id'
 563    and 'zookeeper_node'. In instance where 'broker_id' and/or 'zookeeper_node' is not set the default
 564    setting of broker_id=0 and zookeeper_node=localhost is used. In intance where Zookeeper is running
 565    on same node as Kafka and there is a one to one relationship between Zookeeper and Kafka, default
 566    setting can be used. The docker argument `add-host` adds hostname and IP address to
 567    /etc/hosts file in container
 568
 569 Run zookeeper docker image:
 570
 571 .. code:: bash
 572
 573    $ sudo docker run -tid --net=host -p 2181:2181 zookeeper:3.4.11
 574
 575 Run kafka docker image which connects with a zookeeper instance running on same node with a 1:1 relationship
 576
 577 .. code:: bash
 578
 579    $ sudo docker run -tid --net=host -p 9092:9092 opnfv/barometer-kafka
 580
 581
 582 Run kafka docker image which connects with a zookeeper instance running on a node with IP address of
 583 192.168.121.111 using broker ID of 1
 584
 585 .. code:: bash
 586
 587    $ sudo docker run -tid --net=host -p 9092:9092 --env broker_id=1 --env zookeeper_node=zookeeper --add-host \
 588      zookeeper:192.168.121.111 opnfv/barometer-kafka
 589
 590 Run VES Application docker image
 591 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 592 .. note::
 593    VES application uses configuration file ves_app_config.conf from directory
 594    barometer/3rd_party/collectd-ves-app/ves_app/config/ and host.yaml file from
 595    barometer/3rd_party/collectd-ves-app/ves_app/yaml/ by default. If you wish to use a custom config
 596    file it should be mounted to mount point /opt/ves/config/ves_app_config.conf. To use an alternative yaml
 597    file from folder barometer/3rd_party/collectd-ves-app/ves_app/yaml the name of the yaml file to use
 598    should be passed as an additional command. If you wish to use a custom file the file should be
 599    mounted to mount point /opt/ves/yaml/ Please see examples below
 600
 601 Run VES docker image with default configuration
 602
 603 .. code:: bash
 604
 605    $ sudo docker run -tid --net=host opnfv/barometer-ves
 606
 607 Run VES docker image with guest.yaml files from barometer/3rd_party/collectd-ves-app/ves_app/yaml/
 608
 609 .. code:: bash
 610
 611    $ sudo docker run -tid --net=host opnfv/barometer-ves guest.yaml
 612
 613
 614 Run VES docker image with using custom config and yaml files. In example below yaml/ folder cotains
 615 file named custom.yaml
 616
 617 .. code:: bash
 618
 619    $ sudo docker run -tid --net=host -v ${PWD}/custom.config:/opt/ves/config/ves_app_config.conf \
 620      -v ${PWD}/yaml/:/opt/ves/yaml/ opnfv/barometer-ves custom.yaml
 621
 622 Build and Run LocalAgent and Redis Docker Images
 623 -----------------------------------------------------
 624
 625 Download LocalAgent docker images
 626 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 627
 628 If you wish to use pre-built barometer project's LocalAgent images, you can pull the
 629 images from https://hub.docker.com/r/opnfv/barometer-localagent/
 630
 631 .. note::
 632    If your preference is to build images locally please see sections `Build LocalAgent Docker Image`_
 633
 634 .. code:: bash
 635
 636     $ docker pull opnfv/barometer-localagent
 637
 638 .. note::
 639    If you have pulled the pre-built images there is no requirement to complete steps outlined
 640    in sections `Build LocalAgent Docker Image`_ and you can proceed directly to section
 641    `Run LocalAgent Docker Image`_ If you wish to run the docker images via Docker Compose proceed directly to section `Docker Compose`_.
 642
 643 Build LocalAgent docker image
 644 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 645
 646 Build LocalAgent docker image:
 647
 648 .. code:: bash
 649
 650     $ cd barometer/docker/barometer-dma
 651     $ sudo docker build -t opnfv/barometer-dma --build-arg http_proxy=`echo $http_proxy` \
 652       --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
 653
 654 .. note::
 655    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs
 656    to be passed only if system is behind an HTTP or HTTPS proxy server.
 657
 658 Check the docker images:
 659
 660 .. code:: bash
 661
 662    $ sudo docker images
 663
 664 Output should contain a barometer image:
 665
 666 .. code::
 667
 668    REPOSITORY                   TAG                 IMAGE ID            CREATED             SIZE
 669    opnfv/barometer-dma          latest              2f14fbdbd498        3 hours ago         941 MB
 670
 671 Run Redis docker image
 672 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 673
 674 .. note::
 675    Before running LocalAgent, Redis must be running.
 676
 677 Run Redis docker image:
 678
 679 .. code:: bash
 680
 681    $ sudo docker run -tid -p 6379:6379 --name barometer-redis redis
 682
 683 Check your docker image is running
 684
 685 .. code:: bash
 686
 687    sudo docker ps
 688
 689 Run LocalAgent docker image
 690 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 691 .. note::
 692
 693 Run LocalAgent docker image with default configuration
 694
 695 .. code:: bash
 696
 697    $ cd barometer/docker/barometer-dma
 698    $ sudo mkdir /etc/barometer-dma
 699    $ sudo cp ../../src/dma/examples/config.toml /etc/barometer-dma/
 700    $ sudo vi /etc/barometer-dma/config.toml
 701    (edit amqp_password and os_password:OpenStack admin password)
 702
 703    $ sudo su -
 704    (When there is no key for SSH access authentication)
 705    # ssh-keygen
 706    (Press Enter until done)
 707    (Backup if necessary)
 708    # cp ~/.ssh/authorized_keys ~/.ssh/authorized_keys_org
 709    # cat ~/.ssh/authorized_keys_org ~/.ssh/id_rsa.pub \
 710      > ~/.ssh/authorized_keys
 711    # exit
 712
 713    $ sudo docker run -tid --net=host --name server \
 714      -v /etc/barometer-dma:/etc/barometer-dma \
 715      -v /root/.ssh/id_rsa:/root/.ssh/id_rsa \
 716      -v /etc/collectd/collectd.conf.d:/etc/collectd/collectd.conf.d \
 717      opnfv/barometer-dma /server
 718
 719    $ sudo docker run -tid --net=host --name infofetch \
 720      -v /etc/barometer-dma:/etc/barometer-dma \
 721      -v /var/run/libvirt:/var/run/libvirt \
 722      opnfv/barometer-dma /infofetch
 723
 724    (Execute when installing the threshold evaluation binary)
 725    $ sudo docker cp infofetch:/threshold ./
 726    $ sudo ln -s ${PWD}/threshold /usr/local/bin/
 727
 728 Docker Compose
 729 --------------
 730
 731 Install docker-compose
 732 ^^^^^^^^^^^^^^^^^^^^^^
 733
 734 On the node where you want to run influxdb + grafana or the node where you want to run the VES app
 735 zookeeper and Kafka containers together:
 736
 737 .. note::
 738    The default configuration for all these containers is to run on the localhost. If this is not
 739    the model you want to use then please make the appropriate configuration changes before launching
 740    the docker containers.
 741
 742 1. Start by installing docker compose
 743
 744 .. code:: bash
 745
 746    $ sudo curl -L https://github.com/docker/compose/releases/download/1.17.0/docker-compose-`uname -s`-`uname -m` -o /usr/bin/docker-compose
 747
 748 .. note::
 749    Use the latest Compose release number in the download command. The above command is an example,
 750    and it may become out-of-date. To ensure you have the latest version, check the Compose repository
 751    release page on GitHub.
 752
 753 2. Apply executable permissions to the binary:
 754
 755 .. code:: bash
 756
 757    $ sudo chmod +x /usr/bin/docker-compose
 758
 759 3. Test the installation.
 760
 761 .. code:: bash
 762
 763   $ sudo docker-compose --version
 764
 765 Run the InfluxDB and Grafana containers using docker compose
 766 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 767
 768 Launch containers:
 769
 770 .. code:: bash
 771
 772    $ cd barometer/docker/compose/influxdb-grafana/
 773    $ sudo docker-compose up -d
 774
 775 Check your docker images are running
 776
 777 .. code:: bash
 778
 779    $ sudo docker ps
 780
 781 Connect to <host_ip>:3000 with a browser and log into grafana: admin/admin
 782
 783 Run the Kafka, zookeeper and VES containers using docker compose
 784 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 785
 786 Launch containers:
 787
 788 .. code:: bash
 789
 790    $ cd barometer/docker/compose/ves/
 791    $ sudo docker-compose up -d
 792
 793 Check your docker images are running
 794
 795 .. code:: bash
 796
 797    $ sudo docker ps
 798
 799 Testing the docker image
 800 ^^^^^^^^^^^^^^^^^^^^^^^^
 801 TODO
 802
 803 References
 804 ^^^^^^^^^^^
 805 .. [1] https://docs.docker.com/engine/admin/systemd/#httphttps-proxy
 806 .. [2] https://docs.docker.com/engine/installation/linux/docker-ce/centos/#install-using-the-repository
 807 .. [3] https://docs.docker.com/engine/userguide/
 808
 809