meeresgott/virtualhere-server repository overview

⁠VirtualHere Image

This image is Ubuntu-based and allows sharing USB devices via Docker with VirtualHere. Configuration is done using docker-compose.

⁠Docker Compose Configuration

⁠Configuration Options

To enable auto-discovery for VirtualHere clients, the VirtualHere server needs to be configured with network_mode: host. This allows the server to broadcast its presence on the local network. When using network_mode: host, port mapping (e.g., ports) is not necessary because the service directly uses the host's networking.

⁠Recommended setup

services:
  virtualhere-server:
    image: meeresgott/virtualhere-server
    privileged: true  # Enables access to USB devices on the host
    ports:
      - "7575:7575"  # Port for VirtualHere server
    volumes:
      - /dev/bus/usb:/dev/bus/usb  # Mount USB device path see chapter sharing

⁠Example with auto-discovery

services:
  virtualhere-server:
    image: meeresgott/virtualhere-server
    privileged: true  # Enables access to USB devices on the host
    network_mode: host
    volumes:
      - /dev/bus/usb:/dev/bus/usb  # Mount USB device path see chapter sharing

⁠Share All USB Devices

To share all USB devices, use the following docker-compose configuration:

services:
  virtualhere-server:
    network_mode: host # 
    image: meeresgott/virtualhere-server
    privileged: true  # Enables access to USB devices on the host
    ports:
      - "7575:7575"  # Port for VirtualHere server
    volumes:
      - /dev/bus/usb:/dev/bus/usb  # Mount USB device path

⁠Share a Single USB Device

1. To share a single device, run dmesg | grep tty. This will show a list of connected USB devices, for example:

[ 2177.599924] cdc_acm 1-1:1.1: ttyACM0: USB ACM device

1. Select the device you want to share. In this example, it is ttyACM0. The device is available through the /dev folder.
2. Use the following docker-compose configuration to share the specific device:

services:
  virtualhere-server:
    image: meeresgott/virtualhere-server
    privileged: true  # Required for device access
    ports:
      - "7575:7575"  # Port for VirtualHere server
    devices:
      - /dev/ttyACM0:/dev/ttyACM0  # Shared device

⁠Additional Notes

⁠Explanation for privileged: true

The privileged: true option grants the container extended permissions, ensuring that access to USB devices functions correctly. This is necessary when devices are connected directly to the host and used by containers.

⁠Device Identification

Device names like ttyACM0 can vary depending on the device and system (e.g., ttyUSB0 or ttyS0). Use dmesg to verify that you are using the correct device.

⁠Troubleshooting

If the device is not available as expected, ensure that the host recognizes the device and that no other processes are blocking access. Test access using the VirtualHere client to verify a successful connection.

⁠Share USB Devices Without privileged Mode

Instead of using privileged mode, this configuration demonstrates how to grant specific permissions to USB devices using udev rules and passing the required permissions to the container.

⁠Step-by-step Guide

⁠1. Create Udev Rules

Create a new udev rule to allow access to the specific USB device by creating a file in /etc/udev/rules.d/. For example: /etc/udev/rules.d/99-usb.rules The content of the rule can be as follows (replace ATTRS{idVendor} and ATTRS{idProduct} with the appropriate values for your USB device, which can be found using lsusb):

SUBSYSTEM=="usb", ATTRS{idVendor}=="XXXX", ATTRS{idProduct}=="XXXX", MODE="0666", GROUP="plugdev"

⁠2. Reload Udev Rules

Apply the new udev rules by running the following command:

sudo udevadm control --reload-rules && sudo udevadm trigger

⁠3. Add the Docker User to plugdev Group

Ensure the user running Docker is added to the plugdev group to grant the necessary permissions:

sudo usermod -aG plugdev $USER

You may need to log out and log back in for this change to take effect.

⁠4. Configure docker-compose

Use the following docker-compose configuration to share the USB device without privileged mode:

services:
  virtualhere-server:
    image: meeresgott/virtualhere-server
    ports:
      - "7575:7575"  # Port for VirtualHere server
    devices:
      - /dev/ttyACM0:/dev/ttyACM0  # Replace with the desired device path
    environment:
      - UDEV=1  # Example environment variable to trigger device configuration
    cap_add:
      - SYS_ADMIN  # Adds specific capability instead of using privileged mode