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-pf-docker-images-label:
  79
  80 Building the ONAP Policy Framework Docker Images
  81 ************************************************
  82 If you want to use your own local images, you can build them following these instructions:
  83
  84 **Step 1:** Build the Policy API Docker image
  85
  86 .. code-block:: bash
  87
  88   cd ~/git/onap/policy/api/packages
  89   mvn clean install -P docker
  90
  91 **Step 2:** Build the Policy PAP Docker image
  92
  93 .. code-block:: bash
  94
  95   cd ~/git/onap/policy/pap/packages
  96   mvn clean install -P docker
  97
  98 **Step 3:** Build the Drools PDP docker image.
  99
 100 This image is a standalone vanilla Drools engine, which does not contain any pre-built drools rules or applications.
 101
 102 .. code-block:: bash
 103
 104   cd ~/git/onap/policy/drools-pdp/
 105   mvn clean install -P docker
 106
 107 **Step 4:** Build the Drools Application Control Loop image.
 108
 109 This image has the drools use case application and the supporting software built together with the Drools PDP engine.
 110 It is recommended to use this image if you are first working with ONAP Policy and wish to test or learn how the use
 111 cases work.
 112
 113 .. code-block:: bash
 114
 115   cd ~/git/onap/policy/drools-applications
 116   mvn clean install -P docker
 117
 118 **Step 5:** Build the Apex PDP docker image:
 119
 120 .. code-block:: bash
 121
 122   cd ~/git/onap/policy/apex-pdp
 123   mvn clean install -P docker
 124
 125 **Step 6:** Build the XACML PDP docker image:
 126
 127 .. code-block:: bash
 128
 129   cd ~/git/onap/policy/xacml-pdp/packages
 130   mvn clean install -P docker
 131
 132 **Step 7:** Build the Policy SDC Distribution docker image:
 133
 134 .. code-block:: bash
 135
 136   cd ~/git/onap/policy/distribution/packages
 137   mvn clean install -P docker
 138
 139 **Step 8:** Build the Policy Message Router Simulator
 140
 141 .. code-block:: bash
 142
 143   cd ~/git/onap/policy/models/models-sim/packages
 144   mvn clean install -P docker
 145
 146 Start the containers manually
 147 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 148
 149 **Step 1:** Set the containers location and project.
 150
 151 For *local* images, set CONTAINER_LOCATION="", located at the `export-ports.sh` script
 152 *You will need to build locally all the images using the steps in the previous section*
 153
 154 For *remote* images set CONTAINER_LOCATION="nexus3.onap.org:10001/"
 155
 156
 157 **Step 2:** Set gerrit branch
 158
 159 By default, the `start-compose.sh` script will use the `get-versions.sh` to bring up latest SNAPSHOT version.
 160 To use a different branch, edit the variable GERRIT_BRANCH located at the start of `get-versions.sh` to the
 161 branch needed.
 162
 163
 164 **Step 3:** Get all the images versions
 165
 166 Use the script get-versions.sh
 167
 168 .. code-block:: bash
 169
 170   source ./get-versions.sh
 171
 172
 173 **Step 4:** Run the system using the `start-compose.sh` script
 174
 175 .. code-block:: bash
 176
 177   ./start-compose.sh <component> [--grafana] [--gui]
 178
 179 The <component> input is any of the policy components available:
 180
 181  - api
 182  - pap
 183  - apex-pdp
 184  - distribution
 185  - drools-pdp
 186  - drools-applications
 187  - xacml-pdp
 188  - policy-acm-runtime
 189
 190
 191 Debugging docker containers
 192 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 193
 194 To debug code against docker compose, the java parameters for jmxremote needs to be added to the start script
 195 in the component.
 196
 197 Example:
 198 For Policy PAP, edit the `policy-pap.sh` script:
 199
 200 .. code-block:: bash
 201
 202   vi ~git/onap/policy/pap/packages/policy-pap-docker/src/main/docker/policy-pap.sh
 203
 204
 205 Before the `-jar /app/pap.jar \ ` line, add the following block:
 206
 207
 208 .. code-block:: bash
 209
 210   -Dcom.sun.management.jmxremote.rmi.port=5005 \
 211   -Dcom.sun.management.jmxremote=true \
 212   -Dcom.sun.management.jmxremote.port=5005 \
 213   -Dcom.sun.management.jmxremote.ssl=false \
 214   -Dcom.sun.management.jmxremote.authenticate=false \
 215   -Dcom.sun.management.jmxremote.local.only=false \
 216
 217 On `docker-compose.yml` compose file, add to the port section the mapping 5005.
 218
 219 .. code-block:: yaml
 220
 221   pap:
 222   image: ${CONTAINER_LOCATION}onap/policy-pap:${POLICY_PAP_VERSION}
 223   container_name: policy-pap
 224   depends_on:
 225     - mariadb
 226     - simulator
 227     - api
 228   hostname: policy-pap
 229   ports:
 230     - ${PAP_PORT}:6969
 231     - 5005:5005
 232
 233 That should allow an IDE to connect remotely to the 5005 port.
 234 Follow the instructions of the IDE being used to add a remote connection.
 235
 236 For Intellij, under Run/Debug Configurations, add a new Remote JVM Debug, point Use module classpath to the
 237 <component>-main sub-project.