417 - Welcome & where to start

Welcome to 417!

Below is the “recommended setup” that we will use to run automated tests on. It is your responsibility to ensure that your code works on this setup, as the operation of your code may differ based on the compiler version used, glibc version used, third-party library version used, etc. Please ensure that your code works as intended when it is run in the setup described below.

Do note that you are allowed to create your own setup as per your own preferences to work on, we are asking you to just test them in the below environment to ensure that it actually works. (Test before you submit!)

You will submit the project by committing to your assigned git repository.

Signing in to GitLab and generating SSH keys

We will be using GitLab for all submissions. Please sign in to https://gitlab.cs.umd.edu by clicking on the UMD CAS Login button, and ensure that your GitLab username matches your directory ID (this_part@terpmail.umd.edu).

Then, add an SSH key to your account by following the guide here:

Use SSH keys to communicate with GitLab | GitLab

Git is a distributed version control system, which means you can work locally, then share or push your changes to a server. In this case, the server you push to is GitLab. GitLab uses the SSH protocol to securely communicate with Git.

https://docs.gitlab.com/ee/user/ssh.html

The file id_ed25519 (no extension) is your private key. Treat this like your password and don’t share it with anyone!

The file id_ed25519.pub is your public key. This is the one you register on Gitlab by going to Preferences (User Settings)> SSH Keys.

Installing Docker

Go to https://docs.docker.com/get-docker/ to install Docker. If docker is already installed on your computer, you can skip this step.

If you’re on Windows, make sure to turn on WSL2 integration. More on that here:

Docker Desktop WSL 2 backend on Windows

Windows Subsystem for Linux (WSL) 2 is a full Linux kernel built by Microsoft, which allows Linux distributions to run without managing virtual machines. With Docker Desktop running on WSL 2, users can leverage Linux workspaces and avoid maintaining both Linux and Windows build scripts.

https://docs.docker.com/desktop/windows/wsl/

Then, run our setup script by entering below commands in your command-line.

# replace `~/Desktop` with a directory you want to work on
cd ~/Desktop
# copy the 417docker.sh script from materials to here
git clone git@gitlab.cs.umd.edu:cmsc417-s24/all/materials.git
cp materials/417docker.sh .
# never run shell scripts that you don't understand!
cat 417docker.sh
# make script runnable
chmod +x 417docker.sh
# run the script
./417docker.sh

The script sets up a Debian 12 container, installs all necessary dependencies, and creates a user named student with sudo privileges. You can code, compile, and test in this container.

You will now see a directory named CMSC417 on your ~/Desktop (or wherever you ran the script on). This directory is shared as the home directory for student user in the Docker container, so that you can easily move files around.

The script should have put you on a shell running inside the Docker container. Run cat /etc/os-release in your container shell and check if the output matches exactly as below:

PRETTY_NAME="Debian GNU/Linux 12 (bookworm)"
NAME="Debian GNU/Linux"
VERSION_ID="12"
VERSION="12 (bookworm)"
VERSION_CODENAME=bookworm
ID=debian
HOME_URL="<https://www.debian.org/>"
SUPPORT_URL="<https://www.debian.org/support>"
BUG_REPORT_URL="<https://bugs.debian.org/>"

Also check if file sharing is working as expected. In the shell of your Docker container, do:

# this creates empty file named asdf.txt
cd && touch asdf.txt

And ensure that you can see this file in your host’s CMSC417 directory (you may delete this file after checking that it works.

Working with containers in VSCode

You may use any editor you’d like, but if you don’t have any preferences, I would recommend trying Visual Studio Code, as it has great Docker integration. You can get it from:

Download Visual Studio Code - Mac, Linux, Windows

Visual Studio Code is free and available on your favorite platform - Linux, macOS, and Windows. Download Visual Studio Code to experience a redefined code editor, optimized for building and debugging modern web and cloud applications.

https://code.visualstudio.com/download

Then, install remote containers plugin:

Dev Containers - Visual Studio Marketplace

The Dev Containers extension lets you use a Docker container as a full-featured development environment. Whether you deploy to containers or not, containers make a great development environment because you can: Develop with a consistent, easily reproducible toolchain on the same operating system you deploy to.

https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers

Press Ctrl+Shift+P (Cmd+Shift+P on macOS) to open command palette, and type attach to running container. Press enter.

(Linux only) if you see permission errors, run this on your host shell and reboot: sudo usermod -aG docker $USER

Select cmsc417container and press enter. Now your VSCode runs inside the container environment!

Once you have done this, the remote indicator on the left bottom (green in default theme) should indicate that you’re running inside the container. You may have to re-run attach to running container every time you close and re-open VSCode.

Setting up git/ssh in containers

In your container, create the .ssh directory with command below:

mkdir -p ~/.ssh
chmod 700 ~/.ssh

Now, on your host, find the shared directory and open the .ssh directory you just created (e.g. CMSC417/.ssh). Then find the id_ed25519 file you created in above step (the file I told you to treat like your password) and copy it into here so your container can have access to your remote Git repository.

Then, on your shell, run:

chmod 600 ~/.ssh/*

Checking if you have access

Navigate to https://gitlab.cs.umd.edu/cmsc417-s24/students/YOUR_DIRECTORY_ID and see if you have access (if not, make a private post ASAP)