From 8776c3213bb7aa5f2415ba03dbbd5aae7361ccc9 Mon Sep 17 00:00:00 2001
From: Prasanna Bhat <prasanna.yoga@gmail.com>
Date: Sun, 12 Apr 2020 22:52:07 +0530
Subject: [PATCH] Add README.md, which describes the usage of docker scripts

Signed-off-by: Prasanna Bhat <prasanna.yoga@gmail.com>
---
 scripts/docker/README.md           | 66 ++++++++++++++++++++++++++++--
 scripts/docker/build_cyclonedds.sh |  2 +-
 2 files changed, 64 insertions(+), 4 deletions(-)

diff --git a/scripts/docker/README.md b/scripts/docker/README.md
index 07aedeb..1fda635 100644
--- a/scripts/docker/README.md
+++ b/scripts/docker/README.md
@@ -1,7 +1,67 @@
 # Overview
 
-This contains helper scripts (Linux) to
-- Build docker image (this contains the dependencies of cyclonedds build & can be used to build cyclonedds)
-- Build docker image with pre-built cyclonedds (can be used for quick testing)
+This contains helper scripts to build & run cyclonedds core & example applications in docker.  
+Additionally you can also build a docker image with pre-built cyclonedds examples. This could be useful in quikly trying the examples (both IPC & network communication).
+
+# Bulid docker image 
+There are two docker images you can build.  
+- **ubuntu:cyclonedds** : ubuntu bionic based image that contains dependencies to build cyclonedds. 
+- **cyclonedds:latest** : ubuntu bionic based image with pre-built cyclonedds core & applications (based on the checked out revision).
+
+## How to build the images
+
+### Pre-requisites
+- Linux machine (native / runnin inside VM)
+- Docker (I have tested with 19.03.8, however past versions also would work, as there is no specific dependency)
+
+### Steps
+
+You can use the helper script `./scripts/docker/build_docker_image.sh` to build the docker images.
+
+- Navigate to root of the project.
+- Run the script with -h to display usage.
+```
+./scripts/docker/build_docker_image.sh [images]
+```
+The following images are supported.  
+`ubuntu` : Same as **ubuntu:cyclonedds** , mentioned above.  
+`cyclonedds` : Same as **cyclonedds:latest**, mentioned above.  
+You can run the script with `-h` option to display usage information.  
+- Build cyclonedds core & examples (if you are using **ubuntu:cyclonedds**)
+Use the helper script `./scripts/docker/build_cyclonedds.sh` to build using the currently checked out revision.  
+**NOTE** : You need to run this script from the root of the project.
+
+# Run cyclonedds examples in docker
+You can use either of the above docker images to run the examples.  
+If you use **ubuntu:cyclonedds**, you need to build cyclonedds inside container to build examples.
+Once you have built the cyclonedds , you are ready to run the examples inside docker container.  
+  
+Let's do that !  
+  
+## Run examples inside the same container (uses IPC)  
+- Launch docker container, from the root of the project
+`docker run --name cyclonedds -it -v $(pwd):/cyclonedds --workdir /cyclonedds cyclonedds:latest /bin/bash`
+This will open terminal connected to docker @ root of the project.  
+It will look something like this
+```
+root@22ff409a33e1:/cyclonedds# 
+```
+- Navigate to `/build/bin` to run the example applications.
+- To run another terminal , connected to same docker container, use the following command.
+```
+docker exec -it cyclonedds /bin/bash
+```
+Run the partner example here. This will establish communication over IPC channel.
+
+
+## Run examples in different containers (uses docker networking)
+- Follow the same steps as in the previous section , instead connecting to existing docker container create a new docker container.
+e.g.  
+`docker run --name cyclonedds1 -it -v $(pwd):/cyclonedds --workdir /cyclonedds cyclonedds:latest /bin/bash`  
+**NOTE** : You need to run this script from the root of the project.  
+At this point you can inspect the traffic using wireshark.  
+Open docker network interface (`docker0` on my system) in wireshark.  
+Good news is that wireshark has RTPS dissector.
+
 
 
diff --git a/scripts/docker/build_cyclonedds.sh b/scripts/docker/build_cyclonedds.sh
index 0130335..9297550 100755
--- a/scripts/docker/build_cyclonedds.sh
+++ b/scripts/docker/build_cyclonedds.sh
@@ -13,4 +13,4 @@ docker run -it --rm -v $WORKSPACE/:/cyclonedds --workdir /cyclonedds $IMAGE_NAME
 # Launch the docker after build
 docker run --name $CONTAINER_NAME -it -v $WORKSPACE/:/cyclonedds --workdir /cyclonedds $IMAGE_NAME /bin/bash
 # If you want to connect to the above docker to run cyclonedds examples (multiple apps in separate terminals) , use the below command
-docker exec -it cyclonedds /bin/bash
\ No newline at end of file
+# docker exec -it cyclonedds /bin/bash
\ No newline at end of file