Skip to content

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.

                         +-----------+
                         | 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 registers 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. When the application registers at RouDi it announces its unix domain socket as well to receive responses of requests which will be sent during runtime 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 built iceoryx can be found at /home/user/iceoryx which is bound to /iceoryx. The usage is explained in detail in the icedelivery C++ example.

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.