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