Docker Set Up

1 Install Docker

Ensure that you install Docker or Docker Desktop before the course starts. If you do not have admin rights to install software on your laptop, talk to your local IT for help.

1.1 Linux

Follow the installation instructions for your OS:

After Docker Desktop starts, open the Dashboard and go to Settings ( in the top-right) > General. Follow the instructions in the General section.

1.2 Mac

Visit this page to ensure you have the requirements necessary.

Download Docker Desktop for Mac with Apple Silicon or Intel Chip and follow the installation instructions.

After Docker Desktop starts, open the Dashboard and go to Settings ( in the top-right) > General. Follow the instructions in the General section.

Important

On Macs with Apple Silicon, in Docker Settings > General, check Use Rosetta for x86/amd64 emulation on Apple Silicon.

1.2.1 Running Linux x86_64 Containers on Apple Silicon

Apple Silicon (M-series chips) uses the ARM64 architecture. Many Linux images are built for x86_64 (Intel/AMD). While Docker Desktop has built-in emulation, it can be unstable or fail for specific system calls.

Colima provides a more robust virtualization layer for macOS, allowing you to run a dedicated x86_64 guest environment that handles these containers more reliably.

Installation

Ensure you have Homebrew installed, then run the following to install Colima and its required virtualization dependencies:

brew install colima qemu lima-additional-guestagents

Start the x86_64 Environment

Important

Docker Desktop and Colima should not run at the same time. You must stop Docker Desktop before starting Colima.

# Stop Docker Desktop via CLI (or quit the app manually from the UI)
docker desktop stop

Initialize Colima with x86_64 emulation

colima start --arch x86_64 --cpu 4 --memory 16 --disk 50

File Permissions & Mounting

When mounting local macOS directories into an x86_64 container via Colima, you may encounter Permission Denied errors. This happens because the file ownership mapping between the macOS host and the Linux VM can be problematic. To bypass these issues, it is recommended to mount a Docker native volume (e.g. -v scanpy-labs:/home/jovyan/work) instead of mounting a local directory.

Switching Docker Contexts

Tip

Run docker context ls to verify which engine is currently active. The entry marked with an asterisk (*) is your current target.

You can toggle between the Colima (x86) environment and the native Docker Desktop (ARM) environment using these commands:

To use Colima (x86_64):

docker desktop stop  # Or quit manually from the UI
colima start

To switch back to Docker Desktop (Native):

colima stop
docker desktop start # Or open the app manually from Applications

1.3 Windows

Visit this page to ensure you have the requirements necessary.

Download Docker Desktop for Windows and follow the installation instructions.

After Docker Desktop starts, open the Dashboard and go to Settings ( in the top-right) > General. Follow the instructions in the General section.

After installation, open a PowerShell terminal and try to run docker --version. If that works, Docker is set up.

2 Test installation

From the terminal, type:

docker --version

and then run your first image by typing:

docker run hello-world

If both work as expected, you successfully installed Docker Desktop!

3 Allocate resources

Open the Docker Dashboard when Docker Desktop starts and go to Settings ( in the top-right) > Resources to allocate the following resources:

CPU limit: 8
Memory limit: 12 GB
Swap: 2 GB

On Windows, if WSL engine is used, you might not be able to change resources directly.