Introduction

What is this repository?

This is a template docker-based dev environment. It supports NVIDIA GPUs on Linux, and provides CPU-based containers for macOS (Apple Silicon and Intel).

It currently includes the following tools:

• An assignments directory with notebooks where you populate your code
• A project directory for your project source code. The documentation for the project is stored separately in the docs directory
• A docs directory that contains the source code of Quarto markdown (qmd) and ipynb notebooks content. You use the docs folder to publish your project work

How to Launch the Development Container in VS Code

This repository includes a VS Code development container configuration that can be launched with either CPU or GPU support.

Prerequisites

1. Install VS Code with the "Dev Containers" extension
2. Install Docker and ensure it's running
3. For GPU support: Install NVIDIA Container Toolkit (for Linux) or Docker Desktop with GPU support

IMPORTANT: After the container is launched, you must run the following commands inside the container to set up the environment:

make start                    # Must run inside container (uses uv package manager)
source .venv/bin/activate     # Activate the virtual environment

Critical Note: The make start command (and make venv-recreate) must be executed from within the devcontainer, not on the host machine. The Makefile uses the uv package manager which is only available inside the container and respects container-specific constraints.

Running with Docker Compose (without VS Code)

You can also run the containers directly with Docker Compose:

# Copy environment file
cp .env.example .env

# Build and start the PyTorch GPU container
docker compose up -d torch.dev.gpu

# Exec into the running container
docker compose exec torch.dev.gpu bash

# Or for ROS development
docker compose up -d ros.dev.gpu
docker compose exec ros.dev.gpu bash

macOS Development (Apple Silicon & Intel)

This repository includes dedicated support for macOS users, including both Apple Silicon (M1/M2/M3/M4) and Intel-based Macs.

Important Limitations

GPU Acceleration (MPS) is NOT available inside Docker on macOS. Docker Desktop uses virtualization (HyperKit/Apple Virtualization Framework) which lacks access to Apple's Metal GPU APIs. For GPU-accelerated PyTorch training using MPS, you must run PyTorch natively on macOS, not inside Docker.

For more details, see:

• Apple Silicon GPUs, Docker and Ollama: Pick Two
• PyTorch MPS Backend Documentation

macOS Services

The repository provides macOS-specific services via docker-compose-mac.yml:

• torch.dev.mac: PyTorch development environment (CPU-only)
• ros.dev.mac: ROS 2 Jazzy development environment

Running on macOS

# Copy environment file
cp .env.example .env

# Build and start the PyTorch container for macOS
docker compose -f docker-compose-mac.yml up -d torch.dev.mac

# Exec into the running container
docker compose -f docker-compose-mac.yml exec torch.dev.mac bash

# Or for ROS 2 development
docker compose -f docker-compose-mac.yml up -d ros.dev.mac
docker compose -f docker-compose-mac.yml exec ros.dev.mac bash

VS Code Dev Container for macOS

To use the macOS containers with VS Code, update .devcontainer/devcontainer.json:

{
  "dockerComposeFile": ["../docker-compose-mac.yml"],
  "service": "torch.dev.mac",
  "runServices": ["torch.dev.mac"]
}

GUI Applications (RViz2, etc.) on macOS

Running GUI applications like RViz2 requires XQuartz:

1. Install XQuartz:

   brew install --cask xquartz

2. Open XQuartz and go to Preferences > Security

3. Enable "Allow connections from network clients"

4. Reboot your Mac (required for changes to take effect)

5. After reboot, allow connections:

   xhost +localhost

Troubleshooting: If you see Error: Can't open display: host.docker.internal:0, ensure you have:

• Completed all XQuartz configuration steps above
• Rebooted your Mac after enabling network clients
• Run xhost +localhost in a terminal on the host

For more details, see:

• Installing ROS 2 on macOS with Docker (Foxglove)
• Setup ROS 2 Dev Docker with Emacs in macOS
• Development Container for ROS 2 on ARM64 Mac

Native PyTorch with MPS (Recommended for GPU Training)

If you need GPU acceleration on macOS, install PyTorch natively (outside Docker):

# Create a virtual environment
python3 -m venv .venv-native
source .venv-native/bin/activate

# Install PyTorch with MPS support
pip install torch torchvision torchaudio

# Verify MPS is available
python -c "import torch; print(f'MPS available: {torch.backends.mps.is_available()}')"

See Apple's PyTorch Metal documentation for more details.

Port Customization

You can customize the exposed ports by modifying the .env file. Each service has its own set of port variables:

Dev Service Ports:

• DEV_QUARTO_PORT: Quarto preview server (default: 4100)
• DEV_JUPYTER_PORT: Jupyter notebook server (default: 8888)
• DEV_PORT: Additional development server (default: 8000)

ROS Service Ports:

• ROS_PORT: ROS master port (default: 11311)
• ROS_QUARTO_PORT: Quarto preview server (default: 4180)
• ROS_JUPYTER_PORT: Jupyter notebook server (default: 8880)
• ROS_DEV_PORT: Additional development server (default: 8078)
• FOXGLOVE_PORT: Foxglove bridge WebSocket (default: 8765)

Note: The actual ports exposed will be the values from your .env file.

Service Selection

The repository supports multiple container configurations:

• torch.dev.gpu: PyTorch development environment with GPU support (Linux)
• ros.dev.gpu: ROS 2 (Jazzy) development environment with GPU support (Linux)
• torch.dev.mac: PyTorch development environment for macOS (CPU-only)
• ros.dev.mac: ROS 2 (Jazzy) development environment for macOS

Switching Services

To switch between services, modify the service field in .devcontainer/devcontainer.json:

{
  "service": "torch.dev.gpu"  // or "ros.dev.gpu", "torch.dev.mac", "ros.dev.mac"
}

After changing the service configuration, rebuild the container using VS Code's "Dev Containers: Rebuild Container" command.

Why Two Containers Launch by Default

When VS Code opens the Dev Container, it runs docker-compose up which starts all services defined in docker-compose.yml by default. The "service" field in devcontainer.json only specifies which container VS Code attaches to—it doesn't limit which containers are started.

Both containers share the same network (ai-agents-network), allowing inter-container communication if needed.

To start only a single container, add the runServices property to .devcontainer/devcontainer.json:

{
  "service": "torch.dev.gpu",
  "runServices": ["torch.dev.gpu"]
}

This explicitly tells VS Code to only start the specified service(s) rather than all services in the compose file.

What should I do with it?

• Follow all instructions under resources in the class website as you will need it to submit your work
• Familiarize yourself with the uv package manager as you will use it to build and manage all your dependencies
• Follow the instructions in the course web site under resources to submit your GitHub repo to the course's LMS system (Canvas/Brightspace)

Additional Notes for ROS Development

ROS 2 Discovery Settings (macOS): The macOS containers are configured with ROS_AUTOMATIC_DISCOVERY_RANGE=LOCALHOST and ROS_DOMAIN_ID=42 to ensure proper ROS 2 node discovery within Docker's network isolation.

Foxglove Bridge: Connect to the Foxglove app using:

ros2 launch foxglove_bridge foxglove_bridge_launch.xml

Building ROS Packages: Use the provided aliases:

# Install dependencies
rosdi

# Build with symlink install
cbuild

# Source the workspace
ssetup