Skip to content

Running in Containers#

This guide covers how to run Agnocast applications in Docker containers.

Requirements#

Kernel module on the host#

The Agnocast kernel module (agnocast-kmod) must be installed on the host system — it cannot run inside a container.

Ubuntu hosts — Install via apt as described in Environment Setup.

Non-Ubuntu hosts (or environments where apt is not available) — Build the kernel module from source:

git clone --branch 2.3.3 https://github.com/autowarefoundation/agnocast.git
cd agnocast/agnocast_kmod
make
sudo insmod agnocast.ko

Note

Building from source requires kernel headers for your running kernel. The module supports kernel 5.x and 6.x series.

Device access#

Each container needs access to the Agnocast device file:

docker run --device /dev/agnocast ...

Shared IPC namespace#

Agnocast uses POSIX shared memory (/dev/shm) and POSIX message queues (/dev/mqueue) for inter-process communication. These resources are scoped by the Linux IPC namespace. By default, each Docker container gets its own private IPC namespace, meaning Agnocast processes in different containers cannot communicate with each other.

To enable communication, all Agnocast containers must share the same IPC namespace.

IPC Namespace Configuration#

Option 1: Share the host IPC namespace#

The simplest approach — all containers use the host's IPC namespace:

docker run --ipc=host --device /dev/agnocast ...

This also allows communication between containerized Agnocast processes and processes running directly on the host.

Option 2: Share an IPC namespace between containers#

If you don't want to expose the host IPC namespace, create a shared IPC namespace among containers:

Start the first container with --ipc=shareable:

docker run --ipc=shareable --device /dev/agnocast --name agnocast_main ...

Start subsequent containers joining the first container's IPC namespace:

docker run --ipc=container:agnocast_main --device /dev/agnocast ...

All containers sharing the same IPC namespace can communicate via Agnocast.

Docker Compose Example#

services:
  node_a:
    image: my_ros2_image
    ipc: host
    devices:
      - /dev/agnocast

  node_b:
    image: my_ros2_image
    ipc: host
    devices:
      - /dev/agnocast

Or with a shared IPC namespace between containers only:

services:
  node_a:
    image: my_ros2_image
    ipc: shareable
    devices:
      - /dev/agnocast

  node_b:
    image: my_ros2_image
    ipc: "service:node_a"
    devices:
      - /dev/agnocast