Docker

(Page Work in progress)

Using Docker containers

The current use case for Docker containers is limited to compiling Cholla. Currently, @alwinm believes that it is difficult to get Docker to run Cholla on AMD GPUs, and has not yet experimented with running Cholla with Nvidia GPUs.

# Run docker container interactively with given tagname using shell /bin/bash
docker run -it <TAGNAME> /bin/bash 

# Specific example of above for a container prepared to compile Cholla with CUDA
docker run -it alwinm/cholla:cuda_v0.2 /bin/bash 

# Mounting a volume so you can access host files from within the Docker container
docker run -v <HOST_DIR_ABSOLUTE_PATH>:<DOCKER_DIR_ABSOLUTE_PATH> -it <TAGNAME> /bin/bash

# Specific example assuming you want to access ~/cholla on your host and name it /cholla_docker in the Docker container
docker run -v ~/cholla/:/cholla_docker -it alwinm/cholla:cuda_v0.2 /bin/bash

Creating Docker containers

This section is for Cholla maintainers and contains information for creating and uploading Docker containers.

Prerequisites: install Docker and make a hub.docker.com account, which is like GitHub for docker containers and will allow GitHub actions to download your container after you upload it. Make a text file named "Dockerfile" in an empty directory.

Basic Dockerfile examples:

# A basic ubuntu Docker
FROM ubuntu

# Ubuntu with cuda development tools installed
FROM nvidia/cuda:11.7.1-devel-ubuntu22.04

# Ubuntu with rocm installed
FROM rocm/dev-ubuntu-20.04:5.2.3

Docker terminal commands

# Build Docker container with given tag name using Dockerfile in current directory
docker build -t <tag-name> .

# Run Docker container with given tag name using /bin/bash as the shell
# Note that things you do here will not be saved into the container after you close it
docker run -it <tag-name> /bin/bash

# Rename Docker image when you are ready to push to docker hub
docker tag <source-tag-name> <destination-tag-name>

# Log into your account at hub.docker.com
docker login -u <username> hub.docker.com

# Push your image with tagname to hub.docker.com
docker push <tag-name>

Docker terminal command example of pushing alwinm/test to dockerhub:

docker build -t test .
docker run -it test /bin/bash # during this step, I git clone cholla and make sure it compiles in my container. 
docker tag test alwinm/test
docker login -u alwinm hub.docker.com
docker push alwinm/test

Dockerfile script commands

# FROM starts a docker container using the image name 
FROM <image-name>

# RUN runs the command and saves the resulting difference as a Docker layer
# This example installs git. WARNING: apt-get update must be in same line as apt-get install 
RUN apt-get -y update && apt-get -y install git

# ENV sets an environment variable
# This example tells Cholla to use make.host.github through the environment variable CHOLLA_MACHINE
ENV CHOLLA_MACHINE=github