Details

Note: everything you need to use the CSCI 104 Docker image is provided in the README.

The ch command line tool should handle standard use-scenarios for the docker environment. However, if you're looking to fix issues you're having with the system or are interested in how it works, the following sections provide a thorough explanation of the three main commands used to manage the container.

Starting the Image

Before we actually run a container with our image, we need to know where to mount the course material folder from. Locate wherever you cloned it to on your computer and get the full path. For example, on Windows that path might look like C:\Users\username\Documents\hw-username\, and on macOS it might look like /Users/username/Documents/hw-username.

The base command for running an image is:

# Don't run this yet
docker run image

However, there are several configurations we want to include:

• -v /path/to/material/:/work/ mounts the work folder on our machine to /work in the container
• -d runs the container in the background
• -t allocates a command prompt for us to access when we interact with the container
• --cap-add SYS_PTRACE will allow GDB to correctly access executable runtimes
• --security-opt seccomp=unconfined allows memory allocation and debugging to work correctly
• --name csci104 gives the container a name to reference in other docker commands

Thus, our complete command is:

docker run -v /Users/username/Documents/hw-username/:/work/ -dt --cap-add SYS_PTRACE --security-opt seccomp=unconfined --name csci104 csci104

Or, you can make a copy of the provided setup script, setup.bat for Windows and setup.sh for macOS, and fill in the path to your material folder. After that, simply running that script in the command line will correctly run the Docker container.

Note that you only need to run the Docker container once, as it will remain active in the background until you shut down your computer or manually stop it.

Accessing the Command Line

Finally, to access the command line of the container you've started, we want to use the exec command. We will add two options to make the command prompt usable:

• -i allows the exec to be interactive
• -t provides us access to an actual shell

Thus, the final command is:

docker exec -it csci104 bash

Stopping the Image

First, find the ID of the container you started by running docker container ls. In case you are for any reason running other containers, make sure to locate the one with image csci104.

Now, simply run the Docker kill command with that ID:

docker kill containerid

Or, if you ran the image with the --name flag, you can use its name:

docker kill csci104

Container Helper Config File

In order to keep track of the container we've spawned for ourselves, ch creates an entry in your .ch.yaml file. a file in your "home" directory. On macOS this is usually at /Users/Username/.ch.yaml. On Windows, this file is usually at C:\Users\Username\.ch.yaml.

This file stores the configuration data to start your environment, including where your csci104 work folder is located. When we ch start csci104, ch reads that file for the csci104 configuration and sends a request to the Docker API to create a container with those specifications.

An example .ch.yaml file with a single csci104 environment would look something like this:

envs:
  csci104:
    buildopts: null
    pullopts:
      imagename: usccsci104/docker:20.04
    hostconfig:
      binds:
      - C:\Users\Username\csci104:/work
      securityopt:
      - seccomp:unconfined
      portbindings: {}
      privileged: false
      capadd:
      - SYS_PTRACE
    shell: /bin/bash

This file is written in YAML (a wonderfully recursive acronym for "YAML Ain't Markup Language") and is meant to be human readable and is a superset of JSON.

The top level envs is before our list of environment mappings. The csci104 environment has the following configuration items:

• buildopts: the build options are null since we are not building a Dockerfile but instead using our csci104 pre-built image on Dockerhub
• pullops: this this mapping indicates we are pulling this image from Dockerhub, which is built from our Dockerfile
• hostconfig: this section is what ch uses to run the container when you run ch start csci104
• binds: this section is for a Docker bind mount which "shares" a folder on your local machine to the virtualized csci104 environment where you run your code
• securityopt, capadd: see the starting the image section for more about these options
• shell: this is the shell to use when you run ch shell csci104