Adding a USB device to a Docker container

Adding USB Devices to Docker Containers via Portainer

Portainer is a powerful tool that simplifies Docker management. Instead of using complex terminal commands, you can map USB hardware (serial ports, sensors, modems, etc.) from your host machine to a container with just a few clicks. This is particularly useful for Hubbox Connect X2 users working with external sensors or serial communication.

1. Adding a USB Device to a New Container

When deploying a fresh container, hardware mapping is handled within the Advanced Settings.

Log in to the Portainer dashboard and click the Containers tab.
Click the + Add container button.
Scroll down to Advanced container settings and select the Resources tab.
In the Devices section, click + add device.
Fill in the paths:
- host: /dev/ttyUSB0 (The physical path on your device)
- container: /dev/ttyUSB0 (The path inside the virtual container)

2. Adding USB via Docker Compose (Stacks)

If you are using Stacks to deploy multiple services, define the device directly in your YAML configuration:

version: '3.8'
services:
  app_name:
    image: your_image_here
    devices:
      - "/dev/ttyUSB0:/dev/ttyUSB0"
    restart: always

Click Deploy the stack to apply the hardware mapping to all services defined in the file.

3. Adding USB to an Existing Container

Docker requires a container recreation to recognize new hardware mappings. Portainer makes this seamless:

Select your target container from the Containers list.
Click the Duplicate/Edit button at the top.
Go to the Resources tab at the bottom and click + add device as shown in Step 1.
Click Deploy the container. Confirm the replacement when prompted to apply the changes.

4. Advanced Option: Privileged Mode

For devices that are frequently hot-swapped (plugged in/out) or require deep hardware access, Privileged Mode is the recommended choice:

Navigate to the Runtime & Capabilities tab in container settings.
Toggle the Privileged mode switch to On.

Important Reminder:

After mapping the device, ensure your application (e.g., Node-RED or Python) has read/write permissions for the port. Privileged Mode typically bypasses permission hurdles, but it should be used judiciously for security reasons.

For hardware compatibility lists and Hubbox industrial IoT solutions, visit: www.hubbox.io