Docker Containers

A container-based environment is the best way to work on AI/ML projects. Your class repository provides pre-configured Docker containers with PyTorch, common ML libraries, and a uv-managed virtual environment. Each course has its own repository, and your assignment page links to the right one.

Installing Docker

We recommend VS Code as your IDE due to its support for Dev Containers. Install Docker for your operating system:

Windows.

Install WSL and follow the instructions below to install Docker natively in WSL. Do not install Docker Desktop - all development must happen in the Ubuntu terminal.

# 1. Drop the snap
  sudo snap stop docker
  sudo snap remove --purge docker

  # 2. Install Docker CE (official repo)
  sudo apt-get update
  sudo apt-get install -y ca-certificates curl
  sudo install -m 0755 -d /etc/apt/keyrings
  sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
  sudo chmod a+r /etc/apt/keyrings/docker.asc
  echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
    | sudo tee /etc/apt/sources.list.d/docker.list >/dev/null
  sudo apt-get update
  sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

  # 3. Group + start
  sudo usermod -aG docker "$USER"
  sudo service docker start

  # 4. Re-open WSL shell (group change), then verify the root dir moves off snap
  docker info | grep -iE 'root dir|storage|server version'
  # Expect: Docker Root Dir: /var/lib/docker

Ubuntu

Follow the Docker Engine instructions. Never install Docker as a snap package. The snap version runs under strict AppArmor confinement that only permits bind mounts from a small allow-list.

Apple Silicon (M1/M2/M3/M4)

Containers on a Mac run inside a Linux virtual machine, and Metal is not exposed to it. PyTorch in a container on an M-series Mac therefore runs on the CPU, and the mps device is unavailable. The chip’s GPU sits idle. What follows from that depends on your course. AI and computer vision. Docker is optional. Installing directly on macOS lets PyTorch use the GPU through Metal, which is much faster than the CPU container, at the cost of drifting from the pinned environment. The Working on a Mac guide covers the setup and states the tradeoff in full. If you prefer the container anyway, install Docker Desktop and use torch.dev.cpu. It works, and for small notebooks the difference is not worth the setup. Robotics. Docker is required, and the setup is different from the services on this page. See ROS container.

Configuration

All Docker services read their configuration from a .env file in the repository root. Copy the example to get started:

cp .env.example .env

Key variables:

# .env
UV_EXTRA=gpu                    # PyTorch variant: gpu or cpu
WORKSPACE_DIR=/workspaces/eng-ai-agents
WORKSPACE_USER=vscode
WANDB_API_KEY=your_api_key_here # For experiment tracking (optional)

The docker-compose.yml loads .env via env_file, making all variables available inside every container.

Never commit your .env file to git. It contains your API keys. The repository’s .gitignore already excludes it.

Docker Compose services

Three services are defined in docker-compose.yml:

Service	Container	GPU	Use case
`torch.dev.gpu`	`eng-ai-agents-dev`	NVIDIA (all)	PyTorch notebooks requiring GPU acceleration
`torch.dev.cpu`	`eng-ai-agents-cpu`	None	Lightweight notebooks, CI, non-GPU workloads
`ros.dev.gpu`	`eng-ai-agents-ros`	NVIDIA (all)	ROS2 robotics notebooks with GPU support

All services mount the repository as a workspace volume, so edits on the host are immediately reflected inside the container.

Build targets

Build containers using make from the repository root:

Command	Description
`make docker-build-gpu`	Build the GPU container (`Dockerfile.nvidia.dgpu`)
`make docker-build-cpu`	Build the CPU container (`Dockerfile.cpu.amd64`)
`make docker-build`	Build both GPU and CPU containers

Run targets

Command	Description
`make docker-run-gpu`	Start an interactive GPU container with the workspace mounted
`make docker-run-cpu`	Start an interactive CPU container with the workspace mounted

Development setup

Once inside a container (or on the host with Python 3.11+), use these targets to set up the development environment:

Command	Description
`make start`	Recreate venv, sync dependencies, install package, and register Jupyter kernel
`make install`	Install the package in the virtual environment
`make install-dev`	Install with development extras (linting, testing)
`make install-notebooks`	Install notebook extras and register the Jupyter kernel
`make setup-dev`	Install dev dependencies and set up pre-commit hooks

Port mappings

Each service exposes ports for development tools:

Service	Quarto	Jupyter	Dev
`torch.dev.gpu`	4100	8888	8000
`torch.dev.cpu`	4101	8889	8001
`ros.dev.gpu`	4180	8880	8078

Port mappings can be customized through environment variables in .env (e.g., DEV_JUPYTER_PORT=8888).

Edit this page on GitHub or file an issue.

Academic calendars

Development Environment

Guides

Installing Docker

Windows.

Ubuntu

Apple Silicon (M1/M2/M3/M4)

Configuration

Docker Compose services

Build targets

Run targets

Development setup

Port mappings

​Installing Docker

​Windows.

​Ubuntu

​Apple Silicon (M1/M2/M3/M4)

​Configuration

​Docker Compose services

​Build targets

​Run targets

​Development setup

​Port mappings

Installing Docker

Windows.

Ubuntu

Apple Silicon (M1/M2/M3/M4)

Configuration

Docker Compose services

Build targets

Run targets

Development setup

Port mappings