Usage

The following is a more comprehensive and accessible version of the instructions in the project README. Feel free to leave issues on the repositories with suggestions for clarification.

Installing Docker

You can install Docker by following the instructions on the website.

Configuring Git

If you haven't done so already, make sure that if you're on Windows you've configured git to checkout as-is. You can do this by running (from any path):

C:\Users\username> git config --global core.autocrlf input

Shell Notes

Before we get started, there are a couple things to mention.

• All commands to be entered in a terminal will be prefaced by /path$ for macOS and /path> for Windows.
  • Don't worry if this looks slightly different than your terminal prompt, which might include your username or machine name; ultimately only the path you're working in matters.
• All paths used are examples, and should be replaced with the actual directories you're working with.
  • Our examples will always use username as our example user.
  • The directories /Users/username/Documents/ on macOS and C:\Users\username\Documents\ on Windows is where we'll be working on the respective platforms.

Additionally, we suggest that you create a single cs104 (or otherwise aptly-named) directory to contain all of your CSCI 104 files. This way you can mount the Docker container to one place and have access to anything you might want. We recommend that you do not mount a git repository, as this would prevent you from accessing other repositories from inside your container (as you should never clone a repository inside another repository).

Cloning Docker

We'll start off by navigating to our documents and cloning the Docker repository. This assumes the directory you want to clone everything inside of is a folder in your documents named cs104, but you could replace that with anything. On macOS:

/Users/username$ cd Documents/cs104
/Users/username/Documents/cs104$ git clone https://github.com/csci104/docker

On Windows:

C:\Users\username> cd Documents\cs104
C:\Users\username\Documents\cs104> git clone https://github.com/csci104/docker

Setting Up

To setup, run the setup script from inside the docker directory. During this process, you'll be asked to supply a mount point for the virtual machine. This is essentially asking which folder on your computer you want to share in real time with your Docker container, so it would make sense to choose your cs104 folder or hw-username folder. On macOS:

/Users/username/Documents/cs104$ cd docker
/Users/username/Documents/cs104/docker$ ./unix/setup.sh

On Windows:

If this is your first time running the setup script make sure you run this in an Admin PowerShell:

# must execute this in admin powershell and select [A] to run scripts
Set-ExecutionPolicy RemoteSigned

C:\Users\username\Documents\cs104> cd docker
C:\Users\username\Documents\cs104\docker> .\windows\setup

Assuming everything goes correctly, you'll see that the Docker container has been downloaded and the ch utility is added to manage the environment. ch stores configuration in a file .ch.yaml that will appear on a Unix machine at /Users/username/.ch.yaml and on Windows at C:\Users\username\.ch.yaml. If you edit this file, you'll see that under csci104.hostconfig.binds, there's a line /User/username/cs104:/work or C:\User\username\cs104:/work. The path before the : is what is shared between your container and your local machine, it's where you'll keep your work for CSCI 104. Feel free to change this; it will take effect once you've stopped and restarted the container.

Starting the Container

Generally, you should start the container once and leave it running in the background so that you can open a shell (using ch shell csci104) whenever needed. While not in use it will incur minimal resource usage. Additionally, stopping the image will completely erase any files in the container that are not under /work.

Let's start the container.

ch start csci104

After this command completes, you should receive a message indicating that a container is running. You're ready to go!

Using the Container

For example, choose to mount the directory /Users/me/Documents/cs104/hw-username. Next, on your local machine you create a file test.cpp with some C++ code and put it in that directory. You can use whatever editor you'd like, CLion, Xcode, Sublime, etc., but the most important part is that you can do work on your actual desktop, not the Docker container. To then go and compile that file, you'd do the following.

On macOS:

/Users/username/Documents/cs104/docker$ ch shell csci104
root@docker:/work$ g++ test.cpp -o test  # In the virtual machine compile test.cpp
root@docker:/work$ ./test                # Run the binary
root@docker:/work$ exit                  # Logout (Ctrl+D also works)
/Users/username/Documents/cs104/docker$

On Windows

C:\Users\username\Documents\cs104\docker> ch shell csci104
root@docker:/work$ g++ test.cpp -o test  # In the virtual machine compile test.cpp
root@docker:/work$ ./test                # Run the binary
root@docker:/work$ exit                  # Logout (Ctrl+D also works)
C:\Users\username\Documents\cs104\docker>

You'll notice that the path you mounted always corresponds to /work inside the container. No matter where you set the mount point to in your file system, this is where it'll be accessible.

Using Git

Every time you start and stop using the ch tool, you're actually creating and destroying the Docker instance you're working with. While this sounds drastic, it's not so bad because the files you're working with aren't in the container's file system; they're in yours and Docker just has access to them. That said, there are a couple drawbacks to how this works. Namely, any files you create inside Docker that are not under the mounted directory (/work by default) are destroyed when you stop the container, and that includes SSH keys and git config. As a result, you should always use git from your operating system's command line, and never from Docker. Docker should generally just be used for development-related activities.