Docker Compose architecture for ROS 2: dependency-only images and mounted code

contact@mulhamfetna.com (Mulham Fetna) — Wed, 16 Sep 2026 00:00:00 +0000

Both images hold dependencies and nothing else. The code and the robot model are mounted from your checkout at runtime — so an edit is a five-second restart, not a five-minute rebuild.

The big picture
#

flowchart TB
    subgraph HOST["🐧 Linux host"]
        CAMDEV["/dev/video0"]
        GPU["/dev/dri · Intel iGPU"]
        X11["/tmp/.X11-unix
XWayland :0"]
        SHM["/dev/shm
Fast DDS segments"]
        NET["host network
UDP multicast · domain 42"]
        REPO["repository checkout"]
        subgraph VT["🐳 vision_tracker · 2.9 GB image"]
            VN["vision_tracker_node.py
mediapipe 0.10.14 · OpenCV"]
        end
        subgraph MT["🐳 mujoco_twin · 1.7 GB image"]
            MN["mujoco_twin_node.py
mujoco 3.13.0 · GLFW"]
        end
    end
    CAMDEV --> VN
    GPU --> VN
    GPU --> MN
    X11 <--> VN
    X11 <--> MN
    VN <--> SHM <--> MN
    VN <--> NET <--> MN
    REPO -. "bind mount .:/workspace:ro" .-> VN
    REPO -. "bind mount .:/workspace:ro" .-> MN

Repository layout
#

.
├── docker-compose.yml          # both services, shared namespaces
├── setup_host.sh               # xhost + device checks, once per login
├── vision_tracker/
│   ├── Dockerfile              # ros:jazzy + mediapipe==0.10.14
│   ├── .dockerignore           # src/ is mounted, so keep it out of the build context
│   └── src/vision_tracker_node.py
├── mujoco_twin/
│   ├── Dockerfile              # ros:jazzy + mujoco==3.13.0
│   ├── .dockerignore           # src/ and model/ are mounted
│   ├── src/mujoco_twin_node.py
│   └── model/                  # scene.xml → robot.xml (+ tendons.xml), assets/, config.json
├── standalone/main.py          # the same pipeline, one process
└── docs/

Each service folder is its own build context: editing the vision Dockerfile never invalidates the twin’s image cache, and neither build uploads the 13 MB of meshes it doesn’t need.

Containerizing ROS 2 without losing the hardware

contact@mulhamfetna.com (Mulham Fetna) — Tue, 08 Sep 2026 00:00:00 +0000

Web developers containerize to isolate processes. Roboticists containerize and then spend the rest of the day punching holes back through the isolation — for the camera, the GPU, the display server and the network.

ROS 2 Jazzy is hard-locked to Ubuntu 24.04. That single fact is reason enough to containerize: without it, adopting a ROS distribution means adopting an operating system version, on every machine that will ever run the code.

But a ROS container is a strange artifact. A web service container wants isolation — that is the product. A robotics container needs a webcam, a GPU, a display server and multicast networking, all of which live outside it. You end up building a box and then carefully cutting four holes in it.

Here is every hole in this project’s compose file and what it is for.

Cold start to live tracking. Note hand_msgs being compiled separately inside two different containers — that duplication is deliberate and load-bearing.

flowchart TB
    subgraph HOST["🖥️ Host — Ubuntu / Kubuntu"]
        X11["X11 socket
/tmp/.X11-unix"]
        CAM["/dev/video0"]
        GPU["/dev/dri"]
        NET["host network
UDP multicast"]
    end
    subgraph C["Active containers · ROS_DOMAIN_ID=42"]
        HT["hand_tracker"]
        RV["ros_rviz"]
        TS["topic_sniffer"]
    end
    GZ["gazebo_sim
(commented out)"]:::parked
    classDef parked stroke-dasharray: 5 5,opacity:0.55
    CAM --> HT
    GPU --> HT
    GPU --> RV
    X11 --> HT
    X11 --> RV
    NET <--> HT
    NET <--> RV
    NET <--> TS

Hole 1 — the network wall has to come down
#

network_mode: "host"
ipc: host
pid: host

This is the one that breaks stacks silently, so it is worth understanding rather than copying.

Devops on Mulham Fetna

Docker Compose architecture for ROS 2: dependency-only images and mounted code

The big picture #

Repository layout #

Containerizing ROS 2 without losing the hardware

Hole 1 — the network wall has to come down #

The big picture
#

Repository layout
#

Hole 1 — the network wall has to come down
#