Docker setup

This course assumes access to an x86-64-based Linux machine, and all problem sets and lecture code can run on a Linux host. Although most problem sets and lecture code can also run directly on a Mac OS X host or on Windows Subsystem for Linux, we recommend you at least check your work on Ubuntu or another Linux host, and your work should not accidentally rely on Mac-specific or Windows-specific behavior.

The easiest way to get access to a Linux environment is via Docker. The Docker container-based virtualization service lets you run a minimal CS 61 environment, including Linux, on a Mac OS X or Windows computer, without the overhead of a full virtual machine like VMware Workstation, VMware Fusion, or VirtualBox.

It should be possible to do all CS 61 problem sets on CS 61 Docker.

Advantages of Docker:

• Docker can start and stop virtual machines incredibly quickly.
• Docker-based virtual machines are small and occupy little space on your machine.
• With Docker, you can easily edit your code in your home environment, but compile and run it on a Linux host.

Disadvantages of Docker:

• Docker does not offer a graphical environment. You will need to run all CS 61 programs exclusively in the terminal.
• Docker technology is less user-friendly than virtual machines. You’ll have to type weird commands.
• You won’t get the fun, different feeling of a graphical Linux desktop.

If you choose not to use Docker, use the VM setup instructions.

Creating CS 61 Docker

To prepare to build your Docker environment:

1. Download and install Docker from docker.com.

   On Linux, follow Docker’s instructions. On Mac, follow Docker’s instructions, but make sure you download the correct version for your computer (M1 and M2 Macs need the Apple Chip version, not the Intel Chip version). On Windows, use the Windows instructions below.

   Windows instructions

   Installing Docker on Windows is more complicated than on Mac or Linux. We recommending running Docker from the Windows Subsystem for Linux (WSL). CS 61 infrastructure will not work from a git bash shell.

   Configure developer mode

   1. In Windows Settings, ensure that “Developer Mode” is enabled.

   2. Open Control Panel > Turn Windows features on or off and ensure that “Virtual Machine Platform” and “Windows Subsystem for Linux” are both enabled.

   3. Restart if needed.

   Install Windows Subsystem for Linux

   1. Open a PowerShell prompt in administrator mode.

   2. Run wsl --install and/or wsl --update to install WSL.

   3. Run wsl --set-default-version 2 to ensure you are using the latest version of WSL.

   4. Install a Linux image for WSL from the Microsoft Store. As of this writing, we recommend Ubuntu 22.04.2 LTS. You may have to choose a username and password for this Linux image.

   5. When Linux installation completes, go back to PowerShell and run wsl -l -v. You should see something like this:

        NAME                   STATE           VERSION
      * Ubuntu-22.04           Running         2
      

      with a * before the Ubuntu-22.04 image. If the * does not appear, run wsl --set-default Ubuntu-22.04 to make that the default image for WSL.

   Install Docker

   1. Install Docker for Windows following Docker’s instructions.

   2. Update Docker’s settings.

      • In Settings > General, ensure that “Use the WSL 2 based engine” is selected.
      • In Settings > Resources, make sure that the Ubuntu-22.04 Linux image has Docker integration enabled.
      • “Apply & restart” if you changed any settings.

   Running CS 61 commands

   Once WSL and Docker are set up, you should be able to run CS 61 commands, such as ./cs61-build-docker, from within WSL. Just open WSL by typing wsl at a PowerShell prompt; then type your commands at the WSL Linux image.

   Second option: PowerShell

   After installing WSL 2 and Docker following the above instructions, we have been able to run bash cs61-run-docker direct from PowerShell, without going through WSL.

   PS C:\Users\User> cd cs61-f23-psets\docker
   PS C:\Users\User\cs61-f23-psets\docker> bash cs61-build-docker
   [+] Building 1.8s (19/19)
   ...
    => => naming to docker.io/library/cs61:latest                                  0.0s
   
   What's Next?
     View summary of image vulnerabilities and recommendations → docker scout quickview
   PS C:\Users\User\cs61-f23-psets\docker> cd ..
   PS C:\Users\User\cs61-f23-psets> bash cs61-run-docker
   cs61-user@3e261c0c72b5:~/cs61-psets$ echo Hello from Docker
   Hello from Docker
   cs61-user@3e261c0c72b5:~/cs61-psets$ cs61-docker-version
   16
   

   But if you encounter any problems, use WSL instead.

2. Clone your cs61-psets repository into your files. (See GitHub Setup.)

3. Open a terminal and change into your cs61-psets/docker directory. For instance:

   $ cd ~/cs61-f23-psets-kohler/docker
   

4. Run this command. It will take a while—up to ten minutes.

   $ ./cs61-build-docker
   

   The command starts up a virtual Linux-based computer running inside your computer. It then installs a bunch of software useful for CS 61 on that environment, then takes a snapshot of the running environment. (The snapshot has a name: cs61:latest.) Once the snapshot is created, it’ll take just a second or so for Docker to restart it.

   (Note: The ./cs61-build-docker script is a wrapper around docker build; specifically: docker build -t cs61:latest -f Dockerfile --platform linux/amd64 .)

We may need to change the Docker image during the term. If we do, you’ll update your repository to get the latest Dockerfile, then re-run the ./cs61-build-docker command from Step 4. However, later runs should be faster since they’ll take advantage of your previous work.

Running CS 61 Docker

Our handout repositories, including cs61-lectures and cs61-psets, contain a cs61-run-docker script that provides good arguments and boots Docker into a view of the current directory. We will update this script throughout the term.

Here’s an example of running CS 61 Docker on a Mac OS X host. At first, uname (a program that prints the name of the currently running operating system) reports Darwin. But after ./cs61-run-docker connects the terminal to a Linux virtual machine, uname reports Linux. At the end of the example, exit quits the Docker environment and returns the terminal to Mac OS X.

$ cd ~/cs61-lectures
$ uname
Darwin
$ uname -a
Darwin Eddies-MacBook-Pro.local 20.6.0 Darwin Kernel Version 20.6.0: Wed Jun 23 00:26:27 PDT 2021; root:xnu-7195.141.2~5/RELEASE_ARM64_T8101 arm64
$ ./cs61-run-docker
cs61-user@a47f05ea5085:~/cs61-lectures$ uname
Linux
cs61-user@a47f05ea5085:~/cs61-lectures$ uname -a
Linux a47f05ea5085 5.10.47-linuxkit #1 SMP PREEMPT Sat Jul 3 21:50:16 UTC 2021 x86_64 x86_64 x86_64 GNU/Linux
cs61-user@a47f05ea5085:~/cs61-lectures$ ls
common  cs61-run-docker  docker  README.md
cs61-user@a47f05ea5085:~/cs61-lectures$ exit
exit
$ 

A prompt like cs61-user@a47f05ea5085:~$ means that your terminal is connected to the VM. (The a47f05ea5085 part is a unique identifier for this running VM.) You can execute any Linux commands you want. To escape from the VM, type Control-D or run the exit command.

The script assumes your Docker container is named cs61:latest, as it was above.

Troubleshooting

The Docker application must be running on your computer when you execute ./cs61-run-docker. Otherwise, you might get this message.

$ ./cs61-run-docker 
Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

Solving Git issues within Docker

For security, Git requires you to establish your identity before any action. This means that you need to have your SSH identity available within Docker in order to use Git from inside your container.

The cs61-run-docker script attempts to forward your SSH identity into the container by default on Mac and Linux. However, this sometimes does not work immediately and Git complains with an error like the following:

fatal: detected dubious ownership in repository at '/home/cs61-user/cs61-psets'
To add an exception for this directory, call:

git config --global --add safe.directory /home/cs61-user/cs61-psets

This can sometimes be fixed simply by running the command ls -la, and then attempting the Git command again.

If this doesn't work, this means your SSH identity was not forwarded at all. The simplest solution to this is to create a new SSH identity within the Docker container and add it to Github. Follow the instructions at SSH key setup. Make sure that you do all of the setup inside the Docker container, and be sure to follow the Linux instructions.

Running CS 61 Docker by hand (advanced topic)

If you don’t want to use the script, use a command like the following.

$ docker run -it --platform linux/amd64 --rm -v ~/cs61-lectures:/home/cs61-user/cs61-lectures cs61:latest

Explanation:

• docker run tells Docker to start a new virtual machine.
• -it says Docker should run interactively (-i) using a terminal (-t).
• --platform linux/amd64 says Docker should emulate an x86-64-based machine. It’s necessary to specify this if you have (for example) an Apple M1-based laptop.
• --rm says Docker should remove the virtual machine when it is done.
• -v LOCALDIR:LINUXDUR says Docker should share a directory between your host and the Docker virtual machine. Here, I’ve asked for the host’s ~/cs61-lectures directory to be mapped inside the virtual machine onto the /home/cs61-user/cs61-lectures directory, which is the virtual machine user’s ~/cs61-lectures directory.
• cs61:latest names the Docker image to run (namely, the one you built).

Here’s an example session:

$ docker run -it --platform linux/amd64 --rm -v ~/cs61-psets:/home/cs61-user/cs61-psets cs61:latest
cs61-user@a15e6c4c8dbe:~$ ls
cs61-psets
cs61-user@a15e6c4c8dbe:~$ echo "Hello, world"
Hello, world
cs61-user@a15e6c4c8dbe:~$ cs61-docker-version
13
cs61-user@a15e6c4c8dbe:~$ exit
exit
$