Update docker installation

- update the script usage
- update the individual installation
- add debug section

Issue-ID: POLICY-4595
Change-Id: I39535156ec64252e6a6c07403d78633f4ac88cbe
Signed-off-by: adheli.tavares <adheli.tavares@est.tech>

1 files changed, 135 insertions, 46 deletions

diff --git a/docs/installation/docker.rst b/docs/installation/docker.rst
index 7f038934..f0981af3 100644
--- a/docs/installation/docker.rst
+++ b/docs/installation/docker.rst
@@ -3,16 +3,18 @@
 .. http://creativecommons.org/licenses/by/4.0
 
 
-Policy Docker Installation
+Policy Docker Usage
 --------------------------
 
 .. contents::
-    :depth: 2
+    :depth: 3
 
 
-Starting the ONAP Policy Framework Docker Images
-************************************************
-In order to start the containers, you can use *docker-compose*. This uses the *docker-compose-all.yml* yaml file to bring up the ONAP Policy Framework. This file is located in the policy/docker repository. In the csit folder there are scripts to *automatically* bring up components in Docker, without the need to build all the images locally.
+Starting the ONAP Policy Framework Docker Containers
+****************************************************
+In order to start the containers, you can use *docker-compose*. This uses the *docker-compose.yml* yaml file to
+bring up the ONAP Policy Framework. This file is located in the policy/docker repository. In the csit folder there
+are scripts to *automatically* bring up components in Docker, without the need to build all the images locally.
 
 Clone the read-only version of policy/docker repo from gerrit:
 
@@ -21,69 +23,55 @@ Clone the read-only version of policy/docker repo from gerrit:
   git clone "https://gerrit.onap.org/r/policy/docker"
 
 
-Start the containers automatically
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. note:: The start-all.sh script in policy/docker/csit will bring up all the Policy Framework components, and give the local ip for the GUI. The latest images will be downloaded from Nexus.
-
-.. code-block:: bash
-
-  export CONTAINER_LOCATION=nexus3.onap.org:10001/
-  export PROJECT=pap
-  ./start-all.sh
-
+The docker compose structure
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-To stop them use ./stop-all.sh
+After cloning the docker repository, the scripts and compose files are under the *compose/* folder.
 
 .. code-block:: bash
 
-  ./stop-all.sh
+  docker
+    compose
+      config -- all the components configurations
+      metrics -- configuration for Prometheus server and Grafana dashboards
+      docker-compose.gui.yml -- compose file with gui services
+      docker-compose.yml -- compose file with policy components services, including simulator, prometheus and grafana
+      export-ports.sh -- script to export the http ports for all components and where the images are collected from
+      get-versions.sh -- script to get the latest SNAPSHOT version of images based on branch (master is default)
+      start-compose.sh -- script to start the containers / applications
+      stop-compose.sh -- script to stop the containers / applications
+      wait_for_port.sh -- helper script to allow some wait time before an application is completely up and running
 
 
-Start the containers manually
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-**Step 1:** Set the containers location and project.
+Start the containers automatically
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Assuming all the scripts are being executed from the compose folder.
 
-For *local* images, set CONTAINER_LOCATION="" (or don't set it at all)
-*You will need to build locally all the images using the steps in the next chapter*
-
-For *remote* images set CONTAINER_LOCATION="nexus3.onap.org:10001/"
+To start all components without Policy GUI:
 
 .. code-block:: bash
 
-  export CONTAINER_LOCATION=nexus3.onap.org:10001/
-  export PROJECT=pap
-
-
-**Step 2:** Set gerrit branch
+  ./start-compose.sh
 
-Set GERRIT_BRANCH="master"
-
-Or use the script get-branch.sh
+To start all components with Policy GUI:
 
 .. code-block:: bash
 
-  source ./get-branch.sh
-
+  ./start-compose.sh --gui
 
-**Step 3:** Get all the images versions
-
-Use the script get-versions.sh
+To start all components with Grafana dashboards and Prometheus server:
 
 .. code-block:: bash
 
-  source ./get-versions.sh
+  ./start-compose.sh --grafana
 
+**You now have a full standalone ONAP Policy framework up and running!**
 
-**Step 4:** Run the system using docker-compose
+To stop all containers, use stop-compose.sh
 
 .. code-block:: bash
 
-  docker-compose -f docker-compose-all.yml up <image> <image>
-
-
-**You now have a full standalone ONAP Policy framework up and running!**
+  ./stop-compose.sh
 
 
 Building the ONAP Policy Framework Docker Images
@@ -115,7 +103,9 @@ This image is a standalone vanilla Drools engine, which does not contain any pre
 
 **Step 4:** Build the Drools Application Control Loop image.
 
-This image has the drools use case application and the supporting software built together with the Drools PDP engine. It is recommended to use this image if you are first working with ONAP Policy and wish to test or learn how the use cases work.
+This image has the drools use case application and the supporting software built together with the Drools PDP engine.
+It is recommended to use this image if you are first working with ONAP Policy and wish to test or learn how the use
+cases work.
 
 .. code-block:: bash
 
@@ -143,3 +133,102 @@ This image has the drools use case application and the supporting software built
   cd ~/git/onap/policy/distribution/packages
   mvn clean install -P docker
 
+**Step 8:** Build the Policy Message Router Simulator
+
+.. code-block:: bash
+
+  cd ~/git/onap/policy/models/models-sim/packages
+  mvn clean install -P docker
+
+Start the containers manually
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**Step 1:** Set the containers location and project.
+
+For *local* images, set CONTAINER_LOCATION="", located at the `export-ports.sh` script
+*You will need to build locally all the images using the steps in the previous section*
+
+For *remote* images set CONTAINER_LOCATION="nexus3.onap.org:10001/"
+
+
+**Step 2:** Set gerrit branch
+
+By default, the `start-compose.sh` script will use the `get-versions.sh` to bring up latest SNAPSHOT version.
+To use a different branch, edit the variable GERRIT_BRANCH located at the start of `get-versions.sh` to the
+branch needed.
+
+
+**Step 3:** Get all the images versions
+
+Use the script get-versions.sh
+
+.. code-block:: bash
+
+  source ./get-versions.sh
+
+
+**Step 4:** Run the system using the `start-compose.sh` script
+
+.. code-block:: bash
+
+  ./start-compose.sh <component> [--grafana] [--gui]
+
+The <component> input is any of the policy components available:
+
+ - api
+ - pap
+ - apex-pdp
+ - distribution
+ - drools-pdp
+ - drools-applications
+ - xacml-pdp
+ - policy-acm-runtime
+
+
+Debugging docker containers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To debug code against docker compose, the java parameters for jmxremote needs to be added to the start script
+in the component.
+
+Example:
+For Policy PAP, edit the `policy-pap.sh` script:
+
+.. code-block:: bash
+
+  vi ~git/onap/policy/pap/packages/policy-pap-docker/src/main/docker/policy-pap.sh
+
+
+Before the `-jar /app/pap.jar \ ` line, add the following block:
+
+
+.. code-block:: bash
+
+  -Dcom.sun.management.jmxremote.rmi.port=5005 \
+  -Dcom.sun.management.jmxremote=true \
+  -Dcom.sun.management.jmxremote.port=5005 \
+  -Dcom.sun.management.jmxremote.ssl=false \
+  -Dcom.sun.management.jmxremote.authenticate=false \
+  -Dcom.sun.management.jmxremote.local.only=false \
+
+On `docker-compose.yml` compose file, add to the port section the mapping 5005.
+
+.. code-block:: yaml
+
+  pap:
+  image: ${CONTAINER_LOCATION}onap/policy-pap:${POLICY_PAP_VERSION}
+  container_name: policy-pap
+  depends_on:
+    - mariadb
+    - simulator
+    - api
+  hostname: policy-pap
+  ports:
+    - ${PAP_PORT}:6969
+    - 5005:5005
+
+That should allow an IDE to connect remotely to the 5005 port.
+Follow the instructions of the IDE being used to add a remote connection.
+
+For Intellij, under Run/Debug Configurations, add a new Remote JVM Debug, point Use module classpath to the
+<component>-main sub-project.