Running on GPU under docker

Table of Contents Docker OS images Customize docker image Access GPU under docker Links

Docker OS images

Assuming you are running on some Linux host, install Docker CE. Here are links to install instructions for the few popular OS:

• CentOS
• Ubuntu

By default docker pulls images from the Docker Hub repositories. Each OS image is described by image name and a tag. Knowing them you can get an image as follows:

docker pull <name>:<tag>

For major Linux distributions names and tags are eventually correspond to distribution name and version respectively. Here is helper table for the reference (pay attention to the links to Docker Hub which describe each available image):

Docker Hub Image Link	Name	Tag	Comments
	ubuntu	18.04	Latest LTS
		19.10	Latest rolling release
		rolling	Currently 19.10
		devel	Currently 19.10
	fedora	latest	Currently 30
		30	Latest release
		31	Upcoming release
		rawhide	Latest development
	centos	latest	Currently CentOS 7
		7

Hence, you can install these images as follows:

docker pull ubuntu:19.10
docker pull fedora:30
docker pull centos:7

To further explore images, either search thru Docker Hub or look for images via command line as in example below:

docker search ubuntu

Customize docker image

Once you got desired OS docker image installed, you most likely will need to customize it. Here are few key things to keep in mind.

To access docker shell (very basic non-customized access) run:

#host# docker run -it ubuntu:19.10
root@36401aceffb3:/#

You can install software under docker via usual OS package manager. For example, under Ubuntu 19.10 we can install media stack as described in Intel media stack on Ubuntu:

root@36401aceffb3:/# apt-get install libmfx1 libmfx-tools
root@36401aceffb3:/# apt-get install libva-drm2 libva-x11-2 vainfo
root@36401aceffb3:/# apt-get install intel-media-va-driver-non-free

Mind that once you will logout from the docker image you will need to save your modifications to the image if you want to reuse them later, otherwise docker will just start 'clean' image as if you did nothing. To save your work:

#host# docker commit 36401aceffb3 my_ubuntu

Where 36401aceffb3 is image ID assigned by docker you the image from which you just logged out and my_ubuntu is a new image name (just to avoid overriding clean ubuntu:19.10).

Most likely you will need to access some directories on your home system. For that you need to map them with -v </host/path>:</image/path> argument to docker run:

#host# touch confirm_map.stamp
#host# docker run -v ~:/host_home -it ubuntu:19.10
root@36401aceffb3:/# ls /host_home/confirm_map.stamp
/host_home/confirm_map.stamp

To pass some environment variables to the docker image, use -e NAME=VALUE command:

#host# docker run -it ubuntu:19.10
root@36401aceffb3:/# echo $LIBVA_DRIVER_NAME

#host# docker run -e LIBVA_DRIVER_NAME=iHD -it ubuntu:19.10
root@36401aceffb3:/# echo $LIBVA_DRIVER_NAME
iHD

Access GPU under docker

You won't see GPU under docker by default. To be able to access host system GPU you need to use --privileged argument to docker run command:

#host# docker run -it ubuntu:19.10
root@36401aceffb3:/# ls /dev/dri/*
ls: cannot access '/dev/dri/*': No such file or directory

#host# docker run --privileged -it ubuntu:19.10
root@36401aceffb3:/# ls /dev/dri/*
/dev/dri/card0  /dev/dri/renderD128

After that you should be able to run something on GPU if it does not require on screen rendering. In case of on screen X server rendering you additionally need to pass --net=host argument and point to correct DISPLAY:

#host# docker run --privileged --net=host -e DISPLAY=$DISPLAY -it ubuntu:19.10
root@hostname:/#

If your X server configuration differs from default one, for example if you run under SSH, you might additionally need to pass correct DISPLAY environment variable:

Summarizing all the above, here is some complete example to try out. Example assumes running CentOS 7 connected to the display as a host and Ubuntu 19.10 (or later version) in a container:

#host# docker pull ubuntu:19.10
#host# docker run -it --privileged --net=host \
    -e LIBVA_DRIVER_NAME=iHD -e DISPLAY=$DISPLAY \
    ubuntu:19.10
root@hostname:/# apt-get install wget
root@hostname:/# wget https://fate-suite.libav.org/h264-conformance/AUD_MW_E.264

root@hostname:/# apt-get install libmfx1 libmfx-tools
root@hostname:/# apt-get install libva-drm2 libva-x11-2 vainfo
root@hostname:/# apt-get install intel-media-va-driver-non-free

root@hostname:/# /usr/share/mfx/samples/sample_decode h264 -i AUD_MW_E.264 -r -f 30 -rgb4

On successful run you should see decoding done on Intel GPU and on-screen rendering of the input stream.

Links

• Docker Docs
• Docker Hub