Creating a Docker Container on Windows for a Bmad Distribution

Prerequisites

Docker for Windows requires Hyper-V, which is a component of Windows. Hyper-V is not available on Windows Home edition. You should first verify that virutalization is enabled in your BIOS settings. To enable Hyper-V on Windows, follow the instructions at here.

If you normally run as a non-administrative user (you will of course have to enable Hyper-V, and install Docker as an administrative user), you may need to add that user to the Hyper-V Administrators group. To do so, right click on the start menu icon, select Computer Management, then you can add the non-administrative to the Hyper-V Administrators group via Groups under Local Users and Groups. If the Hyper-V Administrators group doesn't exist, just create it. There is also a docker-users group that will be created after the Docker installation; you will need to add that user to this group as well.

You will need an X server. I recommend VcXsrv; you can obtain an installer from here. Using a different X server should be fine, but you will need a working xauth on the Windows side and will need to make a minor modification to the script that connects to the container.

Installing Docker

Installation instructions for Docker on Windows can be found here. You will be creating a Linux container, not a Windows container. I recommend at least 4 GB of memory and 32 GB of disk be allocated to the Docker VM (this can be adjusted in settings after starting Docker). Do not be overly generous with the RAM allocation, or Docker may not start.

Build the image

The first step in the process is to get what Docker calls an image. Create a folder and place Dockerfile, setup-root.sh, build-bmad.sh, and bashrc there. The open a PowerShell window in that folder and type docker build -t bmad . (don't forget the period). Now go find some way to amuse yourself for a while. If you see Successfully tagged bmad:latest, you have successfully built the image.

Start the container

Now that you have the bmad image, you can create a container for the image and run it. To do that, type docker run -d -ti --name bmad bmad. Alternatively, if you want to make a folder on the host system available to the container, you can type docker run -d -ti -v C:\Users\scootaloo\bmad:/data --name bmad bmad, which will make the folder C:\Users\scootaloo\bmad available in the container as the directory /data. You do not need to be in the build folder to execute the docker run command. You will only need to do this once. If your shut down your machine, you will need to re-start this container (see the instructions below). At this point the container is running, and you are ready to connect to it.

Connect to the container

At this point, make sure your X server is running. The following instructions apply to VcXsrv, but similar instructions will apply for any X server. You should see the icon in your notification area (but with whatever background you happen to have there) if the X server is running. To start the X server, go into the Start menu, select the VcXsrv folder, and select XLaunch (not VcXsrv). Click through the defaults and the server should start.

Now to connect the container. Download run-bmad.ps1. Note that you will need to modify the path to xauth in that script if you use an X server other than VcXsrv. Open a PowerShell window, and execute the script you downloaded. You should now have a bash shell prompt, and tao will be in your path.

When you shut down your system, the docker container will stop. If that happens the run-bmad.ps1 script will not work, since there is no running container to connect to. In that case, you can simply restart the container with docker start bmad.

If you need to edit text files, the container has the standard Linux editors vi and emacs, as well as the Gnome editor gedit.

-- JosephScottBerg - 09 Jul 2020