iox-#924 Add icedocker example readme

doc/website/getting-started/examples/icedocker.md

@@ -0,0 +1,5 @@
+---
+title: Sending and receiving data across multiple docker instances
+---
+
+{! ../iceoryx/iceoryx_examples/icedocker/README.md !}

iceoryx_examples/README.md

@@ -5,6 +5,7 @@
 |[icehello](./icehello/)                     | Sending data to another process                                           | :star:             |
 |[icedelivery](./icedelivery/)               | Sending and receiving data using C++                                      | :star:             |
 |[icedelivery_in_c](./icedelivery_in_c/)     | Sending and receiving data using C                                        | :star:             |
+|[icedocker](./icedocker/)                   | Sending and receiving data across multiple docker instances               | :star:             |
 |[iceoptions](./iceoptions/)                 | Configuring pub/sub settings like history cache size or startup behaviour | :star:             |
 |[complexdata](./complexdata/)               | Sending/receiving some of the iceoryx STL container surrogates            | :star:             |
 |[callbacks](./callbacks/)                   | Implementing event triggered callbacks using C++                          | :star::star:       |

iceoryx_examples/icedelivery_in_c/README.md

@@ -34,7 +34,7 @@ Let's take a look at the `receiving` function that comes with the
 
     ```c
     const char APP_NAME[] = "iox-c-subscriber";
-    iox_runtime_init("APP_NAME");
+    iox_runtime_init(APP_NAME);
     ```
 
  2. We create a subscriber port and subscribe to the service
@@ -109,7 +109,7 @@ Let's take a look at the `sending` function that comes with the
 
     ```c
     const char APP_NAME[] = "iox-c-publisher";
-    iox_runtime_init("APP_NAME");
+    iox_runtime_init(APP_NAME);
     ```
 
  2. We create a publisher with the service

iceoryx_examples/icedocker/README.md

@@ -0,0 +1,118 @@
+# Use Iceoryx In A Docker Environment
+
+## Introduction
+
+Let's assume we are working on a system in which `iox-roudi` runs in a docker
+environment and it should orchestrate two applications which are running again
+in two different docker containers so that we end up with a system of 3
+different docker containers.
+
+To demonstrate the setup we use the 
+[icedelivery C++ example](https://github.com/eclipse-iceoryx/iceoryx/tree/master/iceoryx_examples/icedelivery).
+
+```
+                         +-----------+
+                         | docker 1  |
+                         |           |
+                         | iox-roudi |
+                         +-----------+
+
+       +-------------------+        +--------------------+
+       | docker 2          | send   | docker 3           |
+       |                   |------->|                    |
+       | iox-cpp-publisher | data   | iox-cpp-subscriber |
+       +-------------------+        +--------------------+
+```
+
+## Requirements
+
+### Shared Access to Unix Domain Sockets
+
+Every iceoryx application is registering itself at our central broker RouDi
+by sending a message to the unix domain socket located at
+`IOX_UDS_SOCKET_PATH_PREFIX/roudi` which is defined in the corresponding
+platform settings file `platform_settings.hpp`. In linux the socket file handle
+can be found at `/tmp/roudi`. While registering it announces its unix
+domain socket to roudi for the responses of application requests which were
+send to roudi.
+This socket is stored as well in `/tmp/IOX_RUNTIME_NAME`. The `iox-cpp-publisher`
+runtime has the same name as the binary which leads to the socket
+`/tmp/iox-cpp-publisher`.
+
+### Shared Access to File Locks
+
+Iceoryx applications ensure that every runtime name is unique in the system
+by creating a file lock before creating the runtime. This is stored in 
+`IOX_LOCK_FILE_PATH_PREFIX/IOX_RUNTIME_NAME.lock` whereby 
+`IOX_LOCK_FILE_PATH_PREFIX` is defined in the platform settings file
+`platform_settings.hpp`. When running the icedelivery example in a linux
+environment one can observe
+the lock files `/tmp/roudi.lock`, `/tmp/iox-cpp-subscriber.lock` and
+`/tmp/iox-cpp-publisher.lock`.
+
+### Shared Access to Semaphores and Shared Memory
+
+One of the tasks of the central broker RouDi is to create and distribute shared
+memory. When the `iox-cpp-publisher` would like to send data it acquires a
+pointer to this shared memory, writes the data into it and sends the
+pointer to the `iox-cpp-subscriber` which reads the memory at the received
+memory position.
+Additionally, it is possible to signal events across process boundaries via
+semaphores. For instance to signal a subscriber that data has arrived.
+
+## Implementation
+
+To have shared access to the required resources we have to bind the host 
+filesystem:
+
+ * `/tmp`
+ * `/dev`
+
+into every docker container.
+
+### Terminal Example
+
+We start in 3 separate terminals 3 docker instances. In this example we
+use `archlinux:latest` but one is free to choose any other linux distribution.
+The iceoryx repository which contains an already build iceoryx can be found at
+`/home/user/iceoryx` which is bound to `/iceoryx`. The usage and building is 
+explained in detail in the 
+[icedelivery C++ example](https://github.com/eclipse-iceoryx/iceoryx/tree/master/iceoryx_examples/icedelivery).
+
+#### Terminal 1 (iox-roudi)
+```
+docker run --mount type=bind,source="/dev",target=/dev --mount type=bind,source=/home/user/iceoryx,target=/iceoryx --mount type=bind,source=/tmp,target=/tmp -it archlinux:latest
+
+cd /iceoryx
+./build/iox-roudi
+```
+
+#### Terminal 2 (iox-cpp-publisher)
+```
+docker run --mount type=bind,source="/dev",target=/dev --mount type=bind,source=/home/user/iceoryx,target=/iceoryx --mount type=bind,source=/tmp,target=/tmp -it archlinux:latest
+
+cd /iceoryx
+./build/iceoryx_examples/icedelivery/iox-cpp-publisher
+```
+
+#### Terminal 3 (iox-cpp-subscriber)
+
+```
+docker run --mount type=bind,source="/dev",target=/dev --mount type=bind,source=/home/user/iceoryx,target=/iceoryx --mount type=bind,source=/tmp,target=/tmp -it archlinux:latest
+
+cd /iceoryx
+./build/iceoryx_examples/icedelivery/iox-cpp-subscriber
+```
+
+### docker-compose Example
+
+We can also use `docker-compose` to start our test setup. Our example is coming
+with a configuration file `docker-compose.yml` which can be used from the
+iceoryx root path with the following command:
+
+```
+docker-compose -f iceoryx_examples/icedocker/docker-compose.yml --project-directory . up
+```
+
+We have to set the project directory explicitly so that the mapping of the
+iceoryx root path is working as intended.

iceoryx_examples/icedocker/docker-compose.yml

@@ -0,0 +1,22 @@
+services:
+  roudi:
+    image: archlinux:latest
+    command: /iceoryx/build/iox-roudi
+    volumes:
+      - .:/iceoryx
+      - /dev:/dev
+      - /tmp:/tmp
+  publisher:
+    image: archlinux:latest
+    command: /iceoryx/build/iceoryx_examples/icedelivery/iox-cpp-publisher
+    volumes:
+      - .:/iceoryx
+      - /dev:/dev
+      - /tmp:/tmp
+  subscriber:
+    image: archlinux:latest
+    command: /iceoryx/build/iceoryx_examples/icedelivery/iox-cpp-subscriber
+    volumes:
+      - .:/iceoryx
+      - /dev:/dev
+      - /tmp:/tmp

tools/iceoryx_build_test.sh

@@ -304,6 +304,7 @@ if [ "$OUT_OF_TREE_FLAG" == "ON" ]; then
     # Exclude directories without CMake file from the out-of-tree build
     EXAMPLES=${EXAMPLES/iceensemble/""}
     EXAMPLES=${EXAMPLES/icecrystal/""}
+    EXAMPLES=${EXAMPLES/icedocker/""}
     echo ">>>>>> Start Out-of-tree build <<<<<<"
     echo ${EXAMPLES}
     mkdir -p build_out_of_tree && cd build_out_of_tree