« Back to the main CSCI1660 website

Project 0: Container environment setup

Overview

This guide will demonstrate how to set up the tools and development environment we will use for the remaining projects in this course. We will provide our environment using a container, a technology that provides an abstraction of a separate OS without the full overhead of a Virtual Machine (VM). This container runs a Linux-based operating system, Ubuntu 22.04.

When we grade your work, we will use the same container environment–so if your program works in your container, it should work in our grading environment.

Sound familiar? If you’ve taken CS300 or CS1680, you may have worked with a similar container setup before. Our container uses slightly different components compared to the CS300 or CS1680 container, so if you already have one from another course, you still need to set up this one.

Important: You should aim to complete this setup by process by Wednesday, January 29. When you are done, please fill out this form so we can keep track.

If you run into issues during the process, please let us know by posting on Ed or coming to hours so we can help you debug. If you're having trouble, please indicate this on the form by the deadline so we can follow up with you.

Why are we using these tools?

You’ll be able to develop locally. With the container environment, we can specify a standard development environment you can run on your own machine, so your code can work on any system. Thus, you don’t need to log into the department machines to write/test your code!

What if I don't have (or don't want to use) my own computer?

• For students who do not have access to their own laptop, note that the Brown IT service provides laptops you can borrow for free

• If necessary, it's possible to run our course container environment on department machines–this is a new feature the department is supporting, so we consider it experimental. If you are interested in this option, see this section for some special instructions to follow as you read the rest of this guide.

• You can still work on Project 1 using department machines (and without the container environment), if necessary. However, the Flag and Handin projects will require using containers, so for these you'll need to investigate one of the above options. If you have concerns, please email Nick and we can discuss.

Task: Follow the below instructions to set up your container environment. When you are done, see this section for a short task and a link to a form to let us know you have completed the setup.

Environment setup

To run our environment, you will need to configure Docker, the program that builds and runs the container.

Some of the configuration steps here differ based on your host platform, i.e. the system you are using to run the container, which is probably Windows, macOS, or Linux. Please make sure you follow the correct set of instructions for your platform.

Configure docker

Docker is one of the most popular container solutions and widely used in industry.

1. Download and install Docker Desktop, located here. On Linux machines, follow the instructions here.

Already have docker installed? If you already have Docker installed, we strong recommend updating to the latest version by reinstalling it from Docker's website.

Many odd quirks and bugs can result from using old versions of Docker, so updating now is the best way to avoid weird or difficult-to-diagnose problems later in the semester!

Mac users: We do NOT recommend installing Docker with homebrew. This may install a less-than-latest Docker version, which may cause problems.

2. On Windows or macOS, open the Docker Desktop application after it has been installed. You may see a message similar to “Your Docker is starting…”. Once this message goes away, your Docker has started successfully!

Click for extra instructions for Windows-based systems

To run the following steps in this setup, you will need to set up Windows Subsystem for Linux (WSL). WSL should already be enabled after you install Docker, but you may still need to install a Linux distribution. This will run in an actual Linux VM, and you will run your Docker container within that VM (turtles all the way down for you!).

1. Do I have a Linux distribution (Linux distro) installed?
   • Run wsl -l -v in the Command Prompt or Powershell. If there is only “Docker Desktop” and “Docker Desktop Data”, you do not have a Linux distribution installed. Proceed to step 2.
   • Otherwise, you have a Linux distro installed. Proceed to step 3.
2. Install a Linux Distribution.
   • Run wsl --set-default-version 2 to ensure Ubuntu will be installed under WSL 2.
   • Install “Ubuntu 22.04” from Microsoft Store.
   • Click “Open” after Ubuntu is downloaded. A terminal will open and guide you through the installation process.
3. Ensure your Linux Distribution runs on WSL 2.
   • From the output of wsl -l -v, find out if your Linux distro is using WSL 1 or WSL 2. If it’s WSL1:
     • Run wsl --set-version <distro name> 2 to update your distro to use WSL 2.
4. Set your default Linux distro
   • Run wsl --setdefault <distro-name> to configure your default Linux distro. <distro-name> should be “Ubuntu-22.04” if you installed using step 2.

Enter wsl in your Command Prompt or Powershell, and you’ll enter into your WSL! For the rest of the setup, run commands within your WSL Linux environment, unless otherwise specified.

You will also need to connect Docker with WSL. To do so, open your Docker Desktop’s settings (on its top right corner), click “Resources”, “WSL integration”, then enable integration with your Linux distro. Then, click “Apply and Restart”.

3. Verify Docker is installed by executing the following:

$ docker --version

Once you execute the above command, you should see the Docker version number, for example:

$ docker --version
Docker version 24.0.7, build afdd53b

4. After installing Docker, a Docker process (the Docker daemon) will run in the background. Run the following command to verify:

$ docker info

If you see the following error:

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

it means Docker hasn’t started running yet. On Windows or macOS, ensure your Docker Desktop is running. On Linux, try the command sudo systemctl docker restart in a terminal.

Super important instructions for mac users

We have noticed that some MacOS users may experience issues with files not updating when you save them under some combinations of Docker settings: follow these instructions to check your Docker installation and make sure it's set correctly.

Do not skip this step or you may encounter problems later!

Set up the container environment

In Docker, an environment is defined as a Docker image. An image specifies the OS environment that a container provides, as well as other software dependencies and configurations. The instructions defining an image are specified in a file called the Dockerfile.

Next, you will download the course's setup code and create the CS1660 Docker image!

Instructions for macOS users

If you’re running on macOS, you will need to install a set of Apple-recommended command-line tools via the following command:

xcode-select --install

This ensures that your computer has installed git, a program we’ll use below. Alternatively, you may also download and install git directly, following instructions here. After that, continue with the rest of these instructions.

To set up your environment, do the following:

1. Open a terminal (a WSL terminal, on Windows), and enter the directory on your computer where you want to do your coursework.

Windows Users: For best performance, we recommend choosing a directory in your WSL home directory (eg. ~/cs1660) instead of your main C drive (ie, not under /mnt/c).

For more details on what this means and how to generally work with WSL and Docker, see here.

2. Enter the following command to download our development environment to the new subdirectory <DEV-ENVIRONMENT> (you can choose your own name, without the brackets, <DEV-ENVIRONMENT> is a placeholder):

$ git clone https://github.com/brown-csci1660/container-dev.git DEV-ENVIRONMENT

3. Run cd <DEV-ENVIRONMENT> to enter the directory you just created
4. Inside this directory, do the following:

$ ./run-container setup  # Loads our course docker image

./run-container setup downloads your Docker image, which may take a few minutes–so feel free to take a break!

When the setup completes, Docker may ask you to log into an account with Docker–this is safe to ignore.

Read this if you get errors about permissions on docker.sock

When docker installs itself, it normally sets up your user with permissions to control docker (via a socket file called docker.sock). If you don't have permissions on this socket, you might need to close and reopen your terminal app, or log out and log in again, before the permissions changes take effect.

If you are on Linux: you may also need to add your user to the docker group manually, as follows:

1. Open a terminal and run:

$ sudo usermod -a -G docker YOUR_USERNAME

2. Log out and log back in for the changes to take effect.

We do NOT recommend running ./run-container with sudo. This will start the container, but it could cause other permissions problems later because the script is no longer running as your user. If none of these fixes work, please post on Ed or see Nick during office hours.

Extra instructions for Windows users

We have noticed that Docker might use a lot of memory on Windows due to some open bugs with Docker and WSL (the windows component that provides Linux).

If you notice that other programs slowing down or crashing, or otherwise notice docker using lots of memory, see these instructions for how to check Docker's memory usage and keep it under control.

Why are there two Dockerfiles?

You may notice that there are two Dockerfiles in the docker folder: Dockerfile and Dockerfile.arm64. Why are there two Dockerfiles, when CS1660 only uses one container?

Machines run on different architectures, and we will explore that in our course during the semester. Computers that use an Intel chip runs on Intel’s x86 architecture. Recent Macs released by Apple begin to use Apple silicon, which run on the ARM architecture.

Different architectures use different sets of CPU instructions. Therefore, programs running on different architectures need to be compiled differently.

Students running on ARM machines use Dockerfile.arm64, which installs additional packages to compile x86 binaries on an ARM machine. Other students running on chips that use the x86 architecture use Dockerfile.

Entering the container

Once you have downloaded your Docker image, we need to create a container running the image. In Docker terms, a container is an instance of an image, which is where you will actually do your work. Docker (and other container frameworks) are designed to easily start up and tear down individual containers based on a single image.

You can enter your container as follows:

1. From a terminal on your host system (or a WSL terminal on Windows), make sure you're inside the directory <DEV-ENVIRONMENT>, which is the top-level directory of the repository you cloned earlier.
2. Run the script ./run-container to start the container, and poke around to get a sense of the environment: (Windows users: If you get errors, see this section for help.)

$ ./run-container          # enters your Docker container
cs1660-user@9899143429a2:~$    # you're inside the container!
cs1660-user@9899143429a2:~$ uname
Linux
cs1660-user@9899143429a2:~$ echo "Hello world!"
Hello world!
cs1660-user@9899143429a2:~$ ls -lah
total 24K
drwxr-xr-x 6 cs1660-user cs1660-user  192 Jan 25 22:23 .
drwxr-xr-x 1 root       root         4.0K Jan 25 22:25 ..
-rw-r--r-- 1 cs1660-user cs1660-user  132 Jan 25 22:23 .bash_profile
-rw-r--r-- 1 cs1660-user cs1660-user 4.0K Jan 25 22:23 .bashrc
drwxr-xr-x 3 cs1660-user cs1660-user   96 Feb  1 17:22 etc
-rw-r--r-- 1 cs1660-user cs1660-user   25 Jan 25 22:23 .gdbinit
-rw-r--r-- 1 cs1660-user cs1660-user  813 Jan 25 22:23 .profile
cs1660-user@9899143429a2:~$ exit  # or Ctrl-D

Don’t worry if the number after cs1660-user is different. This is an identifier that uniquely identifies this container.

You may run any Linux commands inside this container, such as running your code for this course. To exit, enter exit or use Ctrl-D.

Resuming your work / Multiple shells

Once you have exited the container, you can open it again by running ./run-container again from the <DEV-ENVIRONMENT> directory. This will restart your current container if it exited in the same state it was in before.

If you want to open another shell in the same container, simply open a new terminal window on your computer, navigate to the <DEV-ENVIRONMENT> directory and run run-container–the script will automatically detect that the container is already running and "attach" itself to the current container.

Working in the container environment

Shared folders

“If my docker container is a separate (virtual) computer than my laptop, how will I move files between the two?”, you may ask. Great question!

Inside of the container, your home directory (/home/cs1660-user, or ~) is actually a mount of the home directory inside your <DEV-ENVIRONMENT> directory. Any changes you make in one will be visible in the other.

At this stage, you should test this out to make sure it works (and to make sure you understand what's happening).

1. Outside the container, go to the directory <DEV-ENVIRONMENT>/home and create a file and a directory.
2. Inside the container, you should see the file and folder you created inside your home directory. Delete the file, and add a file to folder (again, this is just a test to see what's happening).
3. Look at the <DEV-ENVIRONMENT>/home directory outside the container–you should see the changes you made in this directory.

Help

1. Outside of the container, in your <DEV-ENVIRONMENT>/home folder:

$ touch cool_file
$ mkdir awesome_folder
$ cd ..
$ ./run-container

2. Inside the container:

cs1660-user@9899143429a2:~$ ls # Show the file and dir we just created
awesome_folder    cool_file
cs1660-user@9899143429a2:~$ rm cool_file
cs1660-user@9899143429a2:~$ cd awesome_folder
cs1660-user@9899143429a2:~$ touch even_cooler_file
cs1660-user@9899143429a2:~$ exit # or just CTRL-D

3. Back outside the container:

$ cd home            # this enters the mounted directory
$ ls                 # should just show awesome_folder
awesome_folder
$ cd awesome_folder
$ ls                 # should show even_cooler_file
even_cooler_file

Using shared folders

As you work on your code, you can take advantage of shared folders, for example:

• You could clone your repository and use git outside the container, rather than setting up SSH keys inside the container
• You can edit your code outside the container using your favorite graphical editor (VSCode, CLion, …) and the compile/run your work inside the container

Mac Users: files not updating in the container?

If you have issues with changes in shared files not updating inside the container, you may need to check your container file sharing settings. Docker has several methods for sharing files on MacOS–we recommend the VirtioFS method, which seems to be the most stable. To set it up, see here.

If this doesn't solve the problem, you can try this legacy version instead.

If issues persist, please post on Edstem or come to hours! Nick has been working on this problem and is curious to see any issues.

Warning: If you move or rename your <DEV-ENVIRONMENT> directory…

Your Docker container will still try to mount to the original dev-environment path, even after you rename, remove, or move the folder DEV-ENVIRONMENT.

After moving your dev-environment folder, you’ll need to delete the old container and start a new container. You can do so with:

./run-container --clean

You should be able to enter the container, and see all of your work now!
:::

Modifying the container

Once you have a shell inside the container, you can run any Linux command as you would on any other Linux system. Feel free to play around, install packages, etc. The user cs1660-user has passwordless sudo access inside the container, so to install a package you can simply run (eg. for vim):

sudo apt-get install vim

We have pre-installed compilers for the languages you are likely to use in this class. As you work on your projects, please use the versions of the compilers installed here so ensure that we can replicate your work when grading. If you have questions about the environment and our grading procedures, please feel free to check with us.

Rebuilding the container environment (don't do this now, but remember for later)

If you want to start a fresh container, close any container shells you have open (eg. with exit), go to the <DEV-ENVIRONMENT> directory and run ./run-container --clean.

Running ./run-container --clean will remove any custom packages, that you have installed and make a fresh container from the base image. This is because --clean removes any existing cs1660 containers on your system.

If you have custom configurations for your packages, (e.g., a .vimrc file for vim), the configurations are persisted even if you have used --clean. This is because user-specific configurations are stored in ~ (or its sub-directories), which are located in the <DEV-ENVIRONMENT>/home directory on your machine.

Connecting VS Code to the container (optional but recommended)

VS Code has some excellent extensions that allow you to easily connect it to a running Docker container. This means you will be able to view and edit files that are in your container's home directory from within a VS Code window. To use it with our container:

1. First, download and install VS Code if you don't already have it.

2. After you have installed and opened VS Code, navigate to the extensions menu (on the left panel of VS Code), and search for the "Dev Containers" extension by Microsoft. Click "Install" to install the extension.

3. If you have not done so already, switch to a terminal and start your container by running ./run-container, then leave this terminal open. For instructions on how to do this, see here.

4. Now that the container is running, we can tell VSCode to connect to it. To do this, switch to VS Code and click on the the small button in the very bottom left of the window (when you hover over the button, it should say "Open a Remote Window")–you'll see a window like the one in the image below. Click on the option that says "Attach to Running Container…".

4. Select the container you wish to use, i.e. cs1660-container:

Don't see the container? Remember that the container needs to be running for it to show up. This means you should have a terminal open inside your container by running ./run-container. For instructions on starting your container, see here.

5. Once you select the container you want, VS Code should open a new window that looks the same as your normal window, except this one is connected to the container you chose in the previous step. You can confirm this by looking at the bottom left of the new window: it should show the name of the container, like in the image below:

6. In this new window, click on the "Open Folder" option–you should be able to poke around the container's filesystem and open files, just like on your host system! For example, you can look inside your home directory by typing in /home/cs1660-user, which goes to your home directory inside the container (like you were exploring earlier, like you saw in the terminal). As you get set up for the first project, we'll provide info on how to clone your git repository to open it here.

Once you start opening files/folders to work on code, VSCode may prompt you to install tools/plugins to work with different languages. This will occur even if you have these plugins set up on your host system–the instance of VS Code in the container is separate from the host version, so it needs to set up everything again. At first, VS Code might need to install a lot of components, so the installation could take a while. After it finishes, everything should work like a normal VS Code instance!

When you are done

Your container environment should now be set up, yay! 🥳

Task: As practice for working with shell commands–something we'll do more and more throughout the semester, we've hidden a file named flag.txt somewhere in your container's home directory. In your container terminal, look around (cd, ls, find, cat, …) to locate this file.

Hint

On Linux, files starting with a . are considered hidden files and not shown by default using commands like ls. You can see hidden files using ls -la, or by using find.

Once you have found the flag, fill out this form–this will let us know you have set up the environment!

Getting help

If you have questions on any stage of configuring the container environment, please contact us by coming to office hours or posting on EdStem. We are happy to help! In addition, if you notice any components that were particularly unclear–or you solve any issues on your own–please let us know we can update the documentation. We really appreciate your feedback!

Additional resources

Here are some less-common tasks you might to perform with the container environment.

Stopping the container

If something goes wrong with a process running inside the container (sockets that are stuck open, zombie processes, with other running process state), you can stop the container and start it again. This forces Docker to kill all container processes.

To do this:

1. Open a terminal on your host machine (or a WSL terminal on Windows)
2. In your container repository, run ./run-container stop
   This may take a minute or two. If you have any other container terminals (or a container-connected VSCode) open, close them.
3. Run ./run-container to open the container again

Stopping the container will only stop any running container processes, it will not change any files inside the container. If you continue to have issues, you may want to consider resetting your container.

Resetting your container

If you have issues with your container filesystem, you can easily reset it back to the original state when you downloaded the image. This will destroy all changes to the container filesystem, but not your DEV-ENVIRONMENT/home directory.

To do this:

1. Open a terminal on your host machine (or a WSL terminal on Windows)
2. In your container repository, run ./run-container --clean
   This may take a minute or two. If you have any other container terminals open (or a container-connected VSCode), close them.

This should give you a shell in a fresh container. Note that any changes to your container's home directory (ie /home/cs1660-user) are unaffected. If you want to reset any of these files back to their original versions, you can download them from this repo.

FAQ/Common Issues

Windows line endings ("unexpected end of file")

If you see errors along the lines of bash: '\r': command not found or bash: /home/cs1660-user/.bash_profile: line 5: syntax error: unexpected end of file when you running a file in your container directory (such as setup-container, you may need to convert your files’ line endings (characters that delineate the end of a line) from Windows to UNIX (Linux) format.

To do so, do the following:

1. Enter into WSL. You may do so by opening Ubuntu in the start menu or through the wsl command.
2. Use cd to navigate to the folder where you just cloned the setup repository. If you cloned your setup repository to your C: drive, use cd /mnt/c to enter the C: drive from your WSL.
3. Run sudo apt-get update, then install dos2unix with sudo apt-get -y install dos2unix.
4. Run dos2unix ./setup-container (or whichever file is causing the error).
5. Try repeating whatever you were doing again. Hopefully, you shouldn't get any errors anymore!
6. If you still get errors and haven't started using your container yet, try running dos2unix on every file in your container home directory, like this: find . -type f -exec dos2unix {} \;

Note: You may see a similar error when trying to run other files from the container. If this occurs, run dos2unix on the file that had the error and try again, which should correct the issue. If the problem persists, feel free to post on Ed.

Filesystem Performance on Macs

Note: This fix relies on the VirtioFS file sharing mechanism in Docker/MacOS. To use it, you might need to update to the latest version of Docker, and possibly update your MacOS version.

We've noticed issues where Mac users have very slow filesystem performance inside the container–especially in the home directory, which is shared with your host system. Docker has several methods of filesystem sharing–we've seen improved performance by switching to the VirtioFS method. To do this:

1. Open the Docker app and enter the settings menu using the gear icon, which looks like this:
   

2. Under the "Choose file sharing implementation" select the VirtioFS method:
   

3. Click Apply & Restart. (If you have any containers running while changing these settings, you might need to stop them or restart your computer for the changes to take effect.)

4. Close the window and open the settings menu again, then make sure VirtioFS is still selected. If it isn't, restart your computer and try again.

If issues persist, please post on Edstem or come to hours! (You can continue using the container for now, though.)

Legacy MacOS file sharing method

Note: On MacOS, we recommend using Docker with the VirtioFS filesystem option, which should provide better performance than the other options. If you encounter issues, Docker offers an older method that we have used in previous version of the course–it seems stable, but is quite slow.

Only use try this option if you have been directed to use it by the course staff.

Click to show

We've noticed an issue where Mac users have issues syncing files between their host system in the container (we'll talk more about how file syncing works in a moment). To avoid issues later, we recommend that Mac users adjust their Docker settings as follows: 1. Open the Docker app and enter the settings menu using the gear icon, which looks like this:

2. Uncheck the box labeled "Use gRPC FUSE file sharing", which looks like this:
   

3. Click Apply & Restart. (If you have any containers running while changing these settings, you might need to stop them or restart your computer for the changes to take effect.)

4. Close the window and open the settings menu again. Make sure the box is still unchecked. If it isn't, restart your computer and try again.

If issues persist, please post on Edstem or come to hours! (You can continue using the container for now, though.)

Windows: using the container with WSL

Using docker with WSL can have some odd quirks. Over time, we've learned some best practices to help:

Some background: Docker on Windows relies on WSL (Windows Subsystem for Linux), which works by running a Linux virtual machine on your system, and then running Docker containers (like our course container) inside it. When you run the command wsl, you are getting a shell inside this VM.

Why it matters: This is important because the WSL VM has its own filesystem outside of your host system. You can navigate from one to the other quite easily, but in order to set up your files and find them later it's important to know the difference:

• Your standard windows home directory (usually C:\Users\YOUR_USER\ on your host system) is located at /mnt/c/Users/YOUR_USER from inside WSL
• Your WSL home directory is a completely separate directory located at the path ~ (shorthand for /home/YOUR_USER) in WSL. We recommend that you do your work from here–your container will run much faster this way! The caveat is that to access your WSL home directory from your host system, you need to look in a separate drive different from your C: drive. If you haven't done this before, see here for instructions.

When you enter WSL from the terminal, be sure to check which directory you're in. We recommend switching to your WSL home directory (eg. cd ~) before you start cloning your repo.

WSL + git: There are many ways to use git on Windows. For best results, we recommend running the git command from your WSL terminal. To do this, you may need to set up an SSH key or personal access token in your WSL installation. If you have issues with this, let us know!

Accessing your files in WSL

Your WSL filesystem is located in a separate drive from your C drive. To access your files there:

1. Open up your file browser and look in the sidebar on the left–you should see an entry labeled Linux, like the figure below. Expand it and find the entry matching your WSL installation (usually "Ubuntu")

2. Inside your WSL drive (eg. "Ubuntu"), navigate to home/YOUR_USER. This is your WSL home directory! As you work on files from WSL, you should see them here. For example, here's where Nick's container repository lives (under /home/deemer/cs1660/ or ~/cs1660 in WSL):

Windows performance and stability issues

If you use Windows, you might notice your computer slowing down or crashing unpredictably, which may be caused by Docker and/or WSL using too much memory. To check if this is happening, you can open Task Manager and check how much memory is being allocated to WSL's VM (Vmmem) and Docker:

This issue is not specific to our course, but a larger, systemic problem related to the interaction between Docker and WSL–you can read about it here and here.

While there does not seem to be a full resolution yet, we've found some workarounds that have helped users in the past. If you're just setting up your container now, skim over these and then come back here if you encounter issues.

There are two types of workarounds:

• Recommended setup changes: You can adjust some settings now to help control docker's memory usage
• Quick fixes (run as you need them): If the Docker's memory usage gets particularly bad, there are some commands you can run to help bring it under control and get your system back

Please report about your experiences with this issue! We're working to understand this problem and the best ways to solve it. As you work on the projects, please let us know if you have problems by posting on Ed or coming to hours. We want to know what's working and what isn't.

Setup changes

Workaround 0. Make sure Docker is up to date

Make sure you are using the latest version of Docker–this issue is under active development, so you want to make sure you have the latest fixes.

To do this, we recommend downloading and reinstalling docker from Docker's website.

Workaround 1: Limit WSL's memory usage

It's possible to limit the total amount of memory WSL can use–this won't stop the leak, but it will at least prevent WSL from making your system totally unusable.

You can set a memory limit by editing WSL's config file. To do this, take a look at this guide (specifically, this section), for instructions on how to configure WSL and make sure it's set up correctly.

How much memory should you assign to WSL? It depends on how much memory you have on your system, and how much WSL stuff you want to run at once. If you have 8-16GB of memory on your system, set a limit of 2-4GB and increase it if you have issues.

Quick fixes

Quick fix 1: Force WSL to clean up some memory

WSL is actually a lightweight Linux virtual machine (VM) that lives on your system, which runs a modified Linux kernel to do memory management for the processes inside WSL. To help keep the memory usage in check, we can ask WSL kernel to help cleanup unused pages in the memory (info here and here), like this:

1. Open a WSL terminal (Open Command Prompt/Powershell > Enter wsl)

2. Enter the following command (when prompted, enter the password you use to log into Windows):

echo 3 | sudo tee /proc/sys/vm/drop_caches

4. After you run the command, you will not see any terminal output. However, you should see Vmmem's memory usage decrease in Task Manager.

Quick fix 2: Shutdown WSL when you're done working (or when it gets slow)

When you're done working on the container, or you get sick of how much memory WSL is using, you can shut it down completely like this:

1. Save any files you have open in any container/WSL shell.

2. Open Command Prompt/Powershell (no need to run wsl)

3. Run wsl --shutdown. This will stop the WSL system and any containers, freeing up all memory. You will lose any active state in any containers (but not saved files).

After you shutdown WSL, Docker will complain that it was disconnected from WSL. To continue using Docker, close and restart the Docker desktop app.

Extra: Building the container image manually

Our container environment loads a pre-built "image" from our course repository that holds all of the files and settings in our container. This image serves as a read-only "template" for all containers you create with ./run-container.

If you want to build the image locally instead, you can run:

$ ./run-container build-image

This will manually create the image using a Dockerfile and setup scripts in the docker directory. See those files for more details.

If you want to remove your container image to save disk space, you can run:

$ ./run-container clean-image

Using department machines

If you are interested in using the container environment on department systems, you will need to follow a slightly different set up process to configure your development environment. On department systems, our container environment uses a different tool instead of Docker called Podman, which is better designed for systems with many users, like on department systems. Most of the time, you won't need to worry about this, but you'll need to follow a slightly different procedure to set up your environment now.

Warning: Since Podman support in the department is new, we are still working on adapting our course materials to use it. In later projects, you will need to use tools with containers that will be hard to use when connected to a department system remotely via SSH. In particular, if you use a department machine, our second project, Flag, might be difficult to do without physical access to a department machine (ie, going to a CIT computer lab in person).

If you are working on department machines because you had trouble getting Docker running on your own system, we highly recommend coming to talk to us in hours or on Ed to fix the issue–this may be faster for you in the long run.

Otherwise, when the flag project is released, we will follow up with any Podman users with more guidance and any potential workarounds.

Please read the following instructions and keep them in mind as you do the rest of the setup:

1. Before setting up Docker, visit this page and follow the instructions in the "Opt-In" section or instructions on how to enable support on your account. Then, you should be able to log into a department system and follow the instructions in this guide.
2. In the section "Set up the container environment", please run the following command instead of ./run-container setup:

$ ./run-container build-image

This command compiles a special container image designed to run on department machines, which may take 15-20 minutes. After it completes, you can proceed with the rest of the setup.

3. In general, you may notice that ./run-container may take 1-2 minutes each time you run it–this is expected, as department systems need to do extra work when you run this command

Attribution

This setup is a modified version of the setup used by CSCI0300 and reused with permission, which is based on Harvard's CS61.