docs/installation/docker.rst

   1 .. This work is licensed under a
   2 .. Creative Commons Attribution 4.0 International License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4
   5 .. _docker-label:
   6
   7 Policy Docker Usage
   8 --------------------------
   9
  10 .. contents::
  11     :depth: 3
  12
  13
  14 Starting the ONAP Policy Framework Docker Containers
  15 ****************************************************
  16 In order to start the containers, you can use *docker-compose*. This uses the *docker-compose.yml* yaml file to
  17 bring up the ONAP Policy Framework. This file is located in the policy/docker repository. In the csit folder there
  18 are scripts to *automatically* bring up components in Docker, without the need to build all the images locally.
  19
  20 Clone the read-only version of policy/docker repo from gerrit:
  21
  22 .. code-block:: bash
  23
  24   git clone "https://gerrit.onap.org/r/policy/docker"
  25
  26
  27 The docker compose structure
  28 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  29
  30 After cloning the docker repository, the scripts and compose files are under the *compose/* folder.
  31
  32 .. code-block:: bash
  33
  34   docker
  35     compose
  36       config -- all the components configurations
  37       metrics -- configuration for Prometheus server and Grafana dashboards
  38       docker-compose.gui.yml -- compose file with gui services
  39       docker-compose.yml -- compose file with policy components services, including simulator, prometheus and grafana
  40       export-ports.sh -- script to export the http ports for all components and where the images are collected from
  41       get-versions.sh -- script to get the latest SNAPSHOT version of images based on branch (master is default)
  42       start-compose.sh -- script to start the containers / applications
  43       stop-compose.sh -- script to stop the containers / applications
  44       wait_for_port.sh -- helper script to allow some wait time before an application is completely up and running
  45
  46
  47 Start the containers automatically
  48 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  49 Assuming all the scripts are being executed from the compose folder.
  50
  51 To start all components without Policy GUI:
  52
  53 .. code-block:: bash
  54
  55   ./start-compose.sh
  56
  57 To start all components with Policy GUI:
  58
  59 .. code-block:: bash
  60
  61   ./start-compose.sh --gui
  62
  63 To start all components with Grafana dashboards and Prometheus server:
  64
  65 .. code-block:: bash
  66
  67   ./start-compose.sh --grafana
  68
  69 **You now have a full standalone ONAP Policy framework up and running!**
  70
  71 To stop all containers, use stop-compose.sh
  72
  73 .. code-block:: bash
  74
  75   ./stop-compose.sh
  76
  77
  78 Building the ONAP Policy Framework Docker Images
  79 ************************************************
  80 If you want to use your own local images, you can build them following these instructions:
  81
  82 **Step 1:** Build the Policy API Docker image
  83
  84 .. code-block:: bash
  85
  86   cd ~/git/onap/policy/api/packages
  87   mvn clean install -P docker
  88
  89 **Step 2:** Build the Policy PAP Docker image
  90
  91 .. code-block:: bash
  92
  93   cd ~/git/onap/policy/pap/packages
  94   mvn clean install -P docker
  95
  96 **Step 3:** Build the Drools PDP docker image.
  97
  98 This image is a standalone vanilla Drools engine, which does not contain any pre-built drools rules or applications.
  99
 100 .. code-block:: bash
 101
 102   cd ~/git/onap/policy/drools-pdp/
 103   mvn clean install -P docker
 104
 105 **Step 4:** Build the Drools Application Control Loop image.
 106
 107 This image has the drools use case application and the supporting software built together with the Drools PDP engine.
 108 It is recommended to use this image if you are first working with ONAP Policy and wish to test or learn how the use
 109 cases work.
 110
 111 .. code-block:: bash
 112
 113   cd ~/git/onap/policy/drools-applications
 114   mvn clean install -P docker
 115
 116 **Step 5:** Build the Apex PDP docker image:
 117
 118 .. code-block:: bash
 119
 120   cd ~/git/onap/policy/apex-pdp
 121   mvn clean install -P docker
 122
 123 **Step 6:** Build the XACML PDP docker image:
 124
 125 .. code-block:: bash
 126
 127   cd ~/git/onap/policy/xacml-pdp/packages
 128   mvn clean install -P docker
 129
 130 **Step 7:** Build the Policy SDC Distribution docker image:
 131
 132 .. code-block:: bash
 133
 134   cd ~/git/onap/policy/distribution/packages
 135   mvn clean install -P docker
 136
 137 **Step 8:** Build the Policy Message Router Simulator
 138
 139 .. code-block:: bash
 140
 141   cd ~/git/onap/policy/models/models-sim/packages
 142   mvn clean install -P docker
 143
 144 Start the containers manually
 145 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 146
 147 **Step 1:** Set the containers location and project.
 148
 149 For *local* images, set CONTAINER_LOCATION="", located at the `export-ports.sh` script
 150 *You will need to build locally all the images using the steps in the previous section*
 151
 152 For *remote* images set CONTAINER_LOCATION="nexus3.onap.org:10001/"
 153
 154
 155 **Step 2:** Set gerrit branch
 156
 157 By default, the `start-compose.sh` script will use the `get-versions.sh` to bring up latest SNAPSHOT version.
 158 To use a different branch, edit the variable GERRIT_BRANCH located at the start of `get-versions.sh` to the
 159 branch needed.
 160
 161
 162 **Step 3:** Get all the images versions
 163
 164 Use the script get-versions.sh
 165
 166 .. code-block:: bash
 167
 168   source ./get-versions.sh
 169
 170
 171 **Step 4:** Run the system using the `start-compose.sh` script
 172
 173 .. code-block:: bash
 174
 175   ./start-compose.sh <component> [--grafana] [--gui]
 176
 177 The <component> input is any of the policy components available:
 178
 179  - api
 180  - pap
 181  - apex-pdp
 182  - distribution
 183  - drools-pdp
 184  - drools-applications
 185  - xacml-pdp
 186  - policy-acm-runtime
 187
 188
 189 Debugging docker containers
 190 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 191
 192 To debug code against docker compose, the java parameters for jmxremote needs to be added to the start script
 193 in the component.
 194
 195 Example:
 196 For Policy PAP, edit the `policy-pap.sh` script:
 197
 198 .. code-block:: bash
 199
 200   vi ~git/onap/policy/pap/packages/policy-pap-docker/src/main/docker/policy-pap.sh
 201
 202
 203 Before the `-jar /app/pap.jar \ ` line, add the following block:
 204
 205
 206 .. code-block:: bash
 207
 208   -Dcom.sun.management.jmxremote.rmi.port=5005 \
 209   -Dcom.sun.management.jmxremote=true \
 210   -Dcom.sun.management.jmxremote.port=5005 \
 211   -Dcom.sun.management.jmxremote.ssl=false \
 212   -Dcom.sun.management.jmxremote.authenticate=false \
 213   -Dcom.sun.management.jmxremote.local.only=false \
 214
 215 On `docker-compose.yml` compose file, add to the port section the mapping 5005.
 216
 217 .. code-block:: yaml
 218
 219   pap:
 220   image: ${CONTAINER_LOCATION}onap/policy-pap:${POLICY_PAP_VERSION}
 221   container_name: policy-pap
 222   depends_on:
 223     - mariadb
 224     - simulator
 225     - api
 226   hostname: policy-pap
 227   ports:
 228     - ${PAP_PORT}:6969
 229     - 5005:5005
 230
 231 That should allow an IDE to connect remotely to the 5005 port.
 232 Follow the instructions of the IDE being used to add a remote connection.
 233
 234 For Intellij, under Run/Debug Configurations, add a new Remote JVM Debug, point Use module classpath to the
 235 <component>-main sub-project.