Sign inSign up

olorobotics/olo-appliance

By olorobotics

•Updated 3 days ago

Image
Developer tools
0

50K+

olorobotics/olo-appliance repository overview

⁠OLO Appliance - Docker Image

This image runs the OLO Appliance.
This guide focuses only on how to run the image and which options you can configure.

⁠Supported Tags

  • olorobotics/olo-appliance:humble-latest
  • olorobotics/olo-appliance:jazzy-latest

⁠Quick Start (Single Container - Humble, Host Networking Recommended)

docker pull olorobotics/olo-appliance:humble-latest

docker run -d \
  --net=host \
  --name olo-appliance \
  -e OLO_APL_DEVICE_API_KEY="apl_your-device-api-key" \
  -e OLO_APL_APPLIANCE_NAME="My Appliance" \
  -v olo-data:/data \
  olorobotics/olo-appliance:humble-latest

This starts the appliance with persistent storage using the olo-data Docker volume. The appliance resolves its robot identity from the server automatically on first boot.

⁠Minimal Docker Compose Example (Humble)

services:
  olo-appliance:
    image: olorobotics/olo-appliance:humble-latest
    container_name: olo-appliance
    network_mode: host
    environment:
      OLO_APL_DEVICE_API_KEY: "apl_your-device-api-key"
      OLO_APL_APPLIANCE_NAME: "My Appliance"
    volumes:
      - olo-data:/data
    restart: unless-stopped

volumes:
  olo-data:
    driver: local

⁠Configuration

⁠Authentication

The recommended way to authenticate is with a device API key provisioned from the OLO portal:

  • OLO_APL_DEVICE_API_KEY - Device API key (prefix apl_). If omitted, the appliance falls back to the interactive device authorization flow⁠ on startup.
  • OLO_APL_APPLIANCE_NAME - A name for this appliance instance (e.g., My Appliance)

Optional:

  • OLO_APL_ROBOT_ID - Robot ID. Auto-resolved from the server on first boot if not provided. Setting it explicitly skips the initial server round-trip.

You can obtain the device API key from the OLO portal when registering a new appliance.

⁠Device Authorization Flow (Interactive Onboarding)

If no OLO_APL_DEVICE_API_KEY is set, the appliance automatically starts an OAuth 2.0 device authorization flow (RFC 8628). This is useful for first-time setup or environments where pre-provisioning an API key is not practical.

How it works:

  1. The appliance requests a device code from the OLO backend.
  2. A verification URL and user code are printed to the container logs.
  3. Open the URL in a browser and enter the displayed code to authorize.
  4. On success, the API key is persisted to /data/.appliance.json so subsequent restarts authenticate automatically.

To see the prompt, check the container logs:

docker logs olo-appliance

The device flow times out after 30 minutes. If it expires, restart the container to try again.

Starting without an API key (device flow):

docker run -d \
  --net=host \
  --name olo-appliance \
  -e OLO_APL_APPLIANCE_NAME="My Appliance" \
  -v olo-data:/data \
  olorobotics/olo-appliance:humble-latest

# Watch the logs for the authorization prompt
docker logs -f olo-appliance

⁠Optional Configuration

⁠Authentication Options
  • OLO_APL_FORCE_DEVICE_FLOW - Set to true to force the device authorization flow even when a persisted API key exists. Useful for re-provisioning an appliance to a different account or organization.
  • OLO_APL_MANAGEMENT_SECRET - Shared secret for securing management API endpoints (/device-flow/start, /device-flow/status, /device-flow/cancel). When set, requests to these endpoints must include the secret as a Bearer token in the Authorization header. Only needed for advanced or programmatic use.
⁠ROS Bridge

By default, the appliance launches its own rosbridge server on localhost:9090. You can configure it to use an external rosbridge server:

  • OLO_APL_ROSBRIDGE_HOST - Rosbridge server hostname (default: localhost)
  • OLO_APL_ROSBRIDGE_PORT - Rosbridge server port (default: 9090)
  • OLO_APL_DISABLE_LOCAL_ROSBRIDGE - Set to true to disable the built-in rosbridge server

Note: You can also configure rosbridge settings through the Maintenance window in the OLO UI. However, be careful when changing the rosbridge host/port via the UI - the setting must be valid from the container's perspective. For example, if you're using host networking, localhost refers to the host machine. If you're using bridge networking with port mappings, you may need to use the container's internal network address or host.docker.internal (on Docker Desktop) to reach services on the host.

Example connecting to an external rosbridge:

docker run -d \
  --net=host \
  --name olo-appliance \
  -e OLO_APL_DEVICE_API_KEY="apl_your-device-api-key" \
  -e OLO_APL_APPLIANCE_NAME="My Appliance" \
  -e OLO_APL_ROSBRIDGE_HOST="192.168.1.100" \
  -e OLO_APL_ROSBRIDGE_PORT="9090" \
  -e OLO_APL_DISABLE_LOCAL_ROSBRIDGE="true" \
  -v olo-data:/data \
  olorobotics/olo-appliance:humble-latest
⁠Simulation Time
  • OLO_APL_USE_SIM_TIME - Set to true to use simulation time (default: false)
⁠ROS Domain ID
  • ROS_DOMAIN_ID - ROS 2 domain ID for DDS communication (default: 0)
⁠Topic Throttling

Control topic publishing rates to manage bandwidth:

  • OLO_APL_TOPIC_DEFAULT_THROTTLE_HZ - Default throttle frequency in Hz for all topics (leave unset or 0 to disable)
  • OLO_APL_TOPIC_HANDLING_JSON - Complete topic handling configuration as JSON

Example topic handling configuration:

docker run -d \
  --net=host \
  --name olo-appliance \
  -e OLO_APL_DEVICE_API_KEY="apl_your-device-api-key" \
  -e OLO_APL_APPLIANCE_NAME="My Appliance" \
  -e OLO_APL_TOPIC_HANDLING_JSON='{"defaultThrottleFrequency": 20, "throttleTopics": {"/odom": 10, "/camera/image_raw": 5}, "throttleDataTypes": {"sensor_msgs/msg/PointCloud2": 2}}' \
  -v olo-data:/data \
  olorobotics/olo-appliance:humble-latest

Topic Handling Options:

  • defaultThrottleFrequency - Default throttle rate in Hz for all topics
  • throttleTopics - Per-topic throttle rates (highest priority)
  • throttleDataTypes - Per-message-type throttle rates (second priority)

Configuration priority: throttleTopics > throttleDataTypes > defaultThrottleFrequency

⁠External ROS2 Workspace Integration

The appliance can source an external ROS2 workspace, making it aware of custom message types, services, and packages from your robot. This is essential when your robot uses custom interfaces that the appliance needs to understand.

⁠How It Works

Set the ROS2_WS_PATH environment variable to point to a ROS2 workspace inside the container. When the appliance starts, it will source $ROS2_WS_PATH/install/setup.bash after sourcing the base ROS distribution.

⁠Sharing a Workspace Between Containers

The recommended approach is to use a shared Docker volume that contains your built ROS2 workspace. A robot driver container can export its workspace, and the appliance can import it read-only:

services:
  olo-appliance:
    image: olorobotics/olo-appliance:humble-latest
    network_mode: host
    environment:
      OLO_APL_DEVICE_API_KEY: "apl_your-device-api-key"
      OLO_APL_APPLIANCE_NAME: "My Appliance"
      ROS2_WS_PATH: /shared/workspace
    volumes:
      - olo-data:/data
      - ros-workspace:/shared/workspace:ro  # Read-only access to shared workspace

  my-robot-driver:
    image: my-robot-driver:humble-latest
    network_mode: host
    environment:
      EXPORT_WORKSPACE: "1"  # Driver exports its workspace on startup
    volumes:
      - ros-workspace:/shared/workspace:rw  # Read-write to populate the workspace

volumes:
  olo-data:
    driver: local
  ros-workspace:
    driver: local

Key Points:

  • The robot driver mounts the shared volume as read-write (rw) and exports its built workspace
  • The appliance mounts the same volume as read-only (ro) and sources it via ROS2_WS_PATH
  • This allows the appliance to understand custom message types, action definitions, and service interfaces from your robot

⁠Running with Dockerized Robot Drivers

A common deployment pattern is running the OLO Appliance alongside one or more containerized robot drivers. All containers share the host network for ROS 2 DDS discovery to work correctly.

⁠Multi-Container Example

This example shows the appliance running alongside a robot driver, with a shared ROS workspace volume:

services:
  olo-appliance:
    image: olorobotics/olo-appliance:humble-latest
    init: true
    restart: unless-stopped
    stop_signal: SIGINT
    stop_grace_period: 40s
    network_mode: host
    environment:
      OLO_APL_DEVICE_API_KEY: "apl_your-device-api-key"
      OLO_APL_APPLIANCE_NAME: "My Appliance"
      ROS_DOMAIN_ID: 55
      ROS_AUTOMATIC_DISCOVERY_RANGE: SUBNET
      FASTDDS_BUILTIN_TRANSPORTS: UDPv4
      ROS_LOCALHOST_ONLY: 0
      ROS2_WS_PATH: /shared/workspace
    volumes:
      - olo-appliance-data:/data
      - ros-workspace:/shared/workspace:ro

  my-robot-driver:
    image: your-robot-driver:humble-latest
    init: true
    restart: unless-stopped
    stop_signal: SIGINT
    stop_grace_period: 40s
    network_mode: host
    environment:
      ROS_DOMAIN_ID: 55
      ROS_AUTOMATIC_DISCOVERY_RANGE: SUBNET
      FASTDDS_BUILTIN_TRANSPORTS: UDPv4
      ROS_LOCALHOST_ONLY: 0
    volumes:
      - ros-workspace:/shared/workspace:rw
    # If your driver needs hardware access:
    # devices:
    #   - "/dev/ttyUSB0:/dev/ttyUSB0"

volumes:
  ros-workspace:
    driver: local
  olo-appliance-data:
    driver: local
⁠Key Configuration Points
  • network_mode: host - Required for ROS 2 DDS discovery between containers and with nodes on the host/LAN
  • ROS_DOMAIN_ID - Must match across all containers and external ROS nodes
  • ROS_AUTOMATIC_DISCOVERY_RANGE: SUBNET - Allows discovery across the local subnet
  • FASTDDS_BUILTIN_TRANSPORTS: UDPv4 - Forces UDP transport (see Troubleshooting)
  • ros-workspace volume - Shared workspace for custom message types
  • init: true - Proper signal handling for graceful shutdown
⁠Starting Services
# Start all services
docker compose up -d

# Start just the appliance
docker compose up -d olo-appliance

# View logs
docker compose logs -f

⁠Networking & Ports

  • Recommended: host networking
    For most setups, run the appliance with host networking (--net=host or network_mode: host). This is required for ROS 2 DDS discovery to work when your robot is on another computer on the same network, as the container needs to receive multicast packets for node discovery.
    In this mode you do not use -p port mappings; the container shares the host's network stack directly.

  • Optional: Diagnostics / Health API (bridge networking only)
    If you choose to run without host networking (Docker bridge mode), the appliance exposes an internal HTTP endpoint on port 8443 inside the container.

    To access this from outside the container (for basic health checks) in bridge mode, you can publish the port:

    docker run -d \
  --name olo-appliance \
  -e OLO_APL_DEVICE_API_KEY="apl_your-device-api-key" \
  -e OLO_APL_APPLIANCE_NAME="My Appliance" \
  -v olo-data:/data \
  -p 9443:8443 \
  olorobotics/olo-appliance:humble-latest

    Then, for example:

    curl http://localhost:9443/health

    Publishing this port is optional and not required for normal operation.

  • ROS 2 / DDS networking (important)
    Docker's default bridge network blocks multicast traffic, which ROS 2 DDS relies on for node discovery. If your robot is running on another computer on the same network, the appliance will not be able to discover it without host networking.

    When using host networking, you do not use -p port mappings (the container shares the host's ports directly).

⁠Data Persistence

The appliance stores all persistent data under /data inside the container. This unified directory contains:

  • /data/recordings/rosbags - ROS bag recordings
  • /data/script-logs - Script execution logs
  • /data/cached-scripts - Cached scripts
  • /data/scheduled-scripts - Scheduled script data
  • /data/cache/olo-client - OLO client cache

Recommended: Use a named volume for persistence across restarts:

docker volume create olo-data

docker run -d \
  --net=host \
  --name olo-appliance \
  -e OLO_APL_DEVICE_API_KEY="apl_your-device-api-key" \
  -e OLO_APL_APPLIANCE_NAME="My Appliance" \
  -v olo-data:/data \
  olorobotics/olo-appliance:humble-latest

Or with Docker Compose:

services:
  olo-appliance:
    image: olorobotics/olo-appliance:humble-latest
    network_mode: host
    environment:
      OLO_APL_DEVICE_API_KEY: "apl_your-device-api-key"
      OLO_APL_APPLIANCE_NAME: "My Appliance"
    volumes:
      - olo-data:/data

volumes:
  olo-data:
    driver: local

⁠Troubleshooting

⁠ROS 2 DDS Discovery Issues

If you're having issues with ROS 2 nodes not discovering each other (topics not visible, services not found), try forcing the DDS transport to UDPv4:

environment:
  FASTDDS_BUILTIN_TRANSPORTS: UDPv4

Or via command line:

docker run -d \
  --net=host \
  --name olo-appliance \
  -e OLO_APL_DEVICE_API_KEY="apl_your-device-api-key" \
  -e OLO_APL_APPLIANCE_NAME="My Appliance" \
  -e FASTDDS_BUILTIN_TRANSPORTS="UDPv4" \
  -v olo-data:/data \
  olorobotics/olo-appliance:humble-latest

This is particularly helpful when:

  • Running multiple containers on the same host
  • Containers can't see topics from other containers or the host
  • Using certain network configurations or VPNs
⁠Additional DDS Configuration

For more control over ROS 2 discovery:

environment:
  ROS_DOMAIN_ID: 55                          # Match across all nodes
  ROS_AUTOMATIC_DISCOVERY_RANGE: SUBNET      # Discover nodes on local subnet
  ROS_LOCALHOST_ONLY: 0                      # Allow non-localhost communication
  FASTDDS_BUILTIN_TRANSPORTS: UDPv4          # Force UDP transport
⁠Authentication Issues
  • Verify that OLO_APL_DEVICE_API_KEY is set correctly (must start with apl_)
  • If no API key is set, check docker logs olo-appliance for the device authorization flow prompt with a verification URL and user code
  • If the device flow times out (30 minutes), restart the container to start a new flow
  • If the device flow shows "access denied", verify that the authorizing user has the correct permissions in the OLO portal
  • To re-provision an appliance that already has a persisted key, set OLO_APL_FORCE_DEVICE_FLOW=true
  • Check network connectivity to the OLO backend
  • View logs: docker logs olo-appliance
⁠Port Conflicts
  • If port 8443 is in use, change the host port mapping: -p 9443:8443
  • When using host networking, ensure no other services are using port 8443

Tag summary

Content type

Image

Digest

sha256:0d469993d…

Size

2.3 GB

Last updated

3 days ago

docker pull olorobotics/olo-appliance:jazzy-latest