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.

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
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