WRoverSoftware_Docker

Multi-service Docker Compose environment running Ubuntu 22.04 with ROS 2 Humble, Python, and Node.js dependencies.

Used for software development across main rover autonomy, simulation, and web GUI systems for Wisconsin Robotics.

Requirements

• Install WSL2 if on Windows.

  IMPORTANT: All terminal commands should run in the WSL terminal on Windows.

• Install and configure Git, then generate an SSH key for GitHub (see Git and CI/CD training). Ensure ssh-agent is running on your host machine to allow Git operations inside containers.

• Install Docker Desktop on Windows or Docker Desktop on Mac.

• Install make and vcstool in a (WSL) terminal:

  sudo apt update && sudo apt install -y make python3-vcstool

  Install make on Mac by installing Xcode Command Line Tools and vcstool via pip3 install vcstool.

Setup

• Clone this repository:

  git clone git@github.com:WisconsinRobotics/WRoverSoftware_Docker.git
  cd WRoverSoftware_Docker

• Import child repositories (WRoverSoftware, WRoverSoftwareSim, WRoverSoftwareGUI) into the ./workspace directory:

  make setup

• Set safe directory permissions for Git if prompted:

  git config --global --add safe.directory "*"

Build

• Ensure Docker Engine / Docker Desktop is running.

• Build all container images (main, sim, gui):

  make build

  NOTE: You only need to rebuild when a Dockerfile or dependency file changes.

• If running into permission issues on Linux/WSL, see this post.

Run

• Start all container services in the background:

  make up

• Attach an interactive terminal shell to a specific running service:

  make shell-main   # Main ROS 2 autonomy stack
  make shell-sim    # Simulation environment
  make shell-gui    # Web GUI stack

• Stop all running containers and exit:

  make down

Repository & Branch Management

The child repositories inside ./workspace/ are bind-mounted live into their respective containers. Each repository operates independently.

• Check out a different branch for a single repository:

  cd workspace/WRoverSoftwareSim
  git checkout main

• Switch all workspace repositories simultaneously using vcstool:

  vcs custom workspace --args checkout dev

  Note: Do not do this without consulting the software leads

• Check workspace status across all repositories:

  vcs status workspace

Visual Studio Code Setup

• Download VS Code.

• Install the Dev Containers extension in VS Code.

  

• Open the WRoverSoftware_Docker folder in VS Code:

  code .

• Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and select Dev Containers: Open Folder in Container... (or attach to a running container via the Remote Explorer panel).

  

• Choose the .devcontainer configuration for the target service:

  • .devcontainer/main
  • .devcontainer/sim
  • .devcontainer/gui

• To disconnect, click the bottom-left corner of VS Code, select Close Remote Connection, and stop the stack using make down.

  

  

Adding Dependencies & Packages

• ROS 2 & System Dependencies: Add apt packages to the respective service Dockerfile in Dockerfiles/, then rebuild:

  make build

• Python Packages: Add package requirement(s) in requirements.txt, one package per line.

  For consistency, it's best to specify the package version, for example, depthai==3.1.0.

  After adding packages, rebuild the Docker containers using make build.

• Node.js Packages (GUI): Install packages directly inside WRoverSoftwareGUI using npm install <package-name> or update package.json.

• To push dependency or infrastructure changes, open a PR (see Git and CI/CD training).