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.4.0 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) for inter-process communication, and the kernel module scopes publishers and subscribers by the Linux IPC namespace (and ROS_DOMAIN_ID). By default, each Docker container gets its own private IPC namespace, meaning Agnocast processes in different containers cannot share messages through shared memory. They still reach each other automatically through the Bridge over ROS 2 (DDS), with serialization. See Limitations for what this requires.

For zero-copy communication, all Agnocast containers must share the same IPC namespace.

Warning

Sharing an IPC namespace is necessary but not sufficient. Agnocast does not serialize messages, so publisher and subscriber must agree on the exact in-memory layout of every message type. Containers built with different compilers, different rosidl generator versions, or different system libraries can produce mismatched layouts that silently corrupt data. Build all communicating containers from the same workspace and toolchain. See Limitations for details.

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 zero-copy 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 with zero copy.

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

Swapping the host kernel module#

When you need to change the host's agnocast-kmod version independently of the heaphook bundled in the container (for example, after rolling the container image to a new version, or to reproduce a bug on an older kmod), use switch_kmod.bash:

sudo ./scripts/switch_kmod.bash <VERSION>
# e.g.
sudo ./scripts/switch_kmod.bash 2.4.0

The script unloads the current module, purges every installed agnocast-kmod-v* package, cleans any leftover DKMS state, installs the target from apt, and verifies the new load via dmesg.

Warning

All Agnocast containers and ROS nodes must be stopped before running this script — the module cannot be unloaded while /dev/agnocast is held open.

Warning

The kmod version on the host must match the major and minor version of agnocastlib inside the container, and libagnocast_heaphook.so must match agnocastlib exactly. On a mismatch, Agnocast processes exit at startup. This script does not touch the container; it is the operator's responsibility to roll the container to a matching version.

After the swap, verify that the host kmod, the in-container libagnocast_heaphook.so, and the in-container agnocastlib are on compatible versions by running

source <your-workspace>/install/setup.bash   # must include the ros2agnocast package
ros2 agnocast -v

inside the container where your Agnocast application actually runs. The command prints the detected kmod / heaphook / agnocastlib versions and flags any incompatibility.