Docker Desktop Setup
The setup steps require using the command-line interface (CLI) from your host operating system. You will be using a CLI very frequently as part of your work in this class, so we recommend finding a setup that you are comfortable with. Commands are entered into a “Terminal” application. Examples of such applications for Mac include Terminal and iTerm2. Examples for Windows include PowerShell and Windows Terminal (please do not use the Windows Command Prompt (CMD) when executing commands for this course).
Another options for those using windows is Windows Subsystem for Linux (WSL). Links for setting it up can be found here: WSL Install. Here is another link that can be useful for further setting up your envinronment: Setting up a WSL Development Enviornment.
Step 1. Install Docker
If you have Docker environment (Docker Engine or Docker Desktop) installed on your computer already, you can skip this step.
Follow Get Docker | Docker Documentation to install Docker Desktop on your operating system. Make sure to follow the one with your corresponding operating system and architecture. The instructions would often include multiple ways to install Docker Desktop on your computer, following one of them is enough.
If you use a Linux distribution that is not supported by Docker Desktop (an unsupported architecture or without a desktop environment), you can follow Install Docker Engine | Docker Documentation to install Docker Engine on your computer.
Once the installation is finished, start Docker Desktop and accept the terms. You should see an interface similar to this:
Give it some time and wait until this message goes away. Your Docker Desktop should now be running if you are greeted with the tutorial page and no error messages come up.
You should skip the tutorial provided by Docker Desktop.
Step 2. Create a Docker Container
You only need to set this up once.
Open a new terminal window. By default it should start under your current user’s directory. You can use the pwd command to print your terminal’s current path:
pwd
To see all of the files and directories within the current working directory, you can use the ls command:
ls
If you don’t want to store your project files under the current working directory, you can use the cd command to “change directory” in your terminal. For example, you can navigate to the Documents directory (if it already exists, relative to your current working directory) with the following command:
cd Documents
If you need to make a new directory, you can do so using the mkdir command. For example, you can make a directory named moya_container in the current working directory as follows:
mkdir moya_container
Then you can change to the newly created directory using cd:
cd moya_container
Using pwd, note where your created directory is, which may come in handy in the future.
Now execute the following command, given that the current working directory is the one created above:
docker run -td --user moya -v "${PWD}:/home/moya/shared" -p 4096:4096 --name moya-container tqmcgaha/docker-env:moya
This command line will pull (download) tqmcgaha/docker-env:moya Docker Image onto your computer, and then create a new Docker Container named moya-container using that Image. The path /home/moya/shared inside the container is mapped to the current working directory of your host system (${PWD}).
If you want to know more about the meaning of these command line arguments, please refer to docker run or Docker Documentation.
Now you should have the container moya-container created and running. You should be able to see this container in Docker Desktop’s Containers tab, or using docker ps command.
Step 3. Use the Docker Container
After you finished Step 2, you can now execute this command to spawn and attach to a shell inside the Docker Container:
docker exec -it moya-container bash
If you want to know more about the meaning of these command line arguments, please refer to docker exec or Docker Documentation.
If you see the following error, maybe after a computer reboot:
Error response from daemon: Container [...] is not running
Then click the start button for the container in Docker Desktop, or use docker start moya-container to start the container.
When you execute any commands related to this class from now on, make sure to execute them inside the Docker Container. One way to distinguish between if you are inside the Docker is to pay attention to the prompt text: if you are in the Docker Container, the prompt should be something similar to
moya@4d98e91a6924:~/shared$
Another way, for example, is to execute docker command. If you are outside Docker (on your host OS), docker command should output a list of help texts; If you are inside Docker, executing docker command should give you docker: command not found error.
********IMPORTANT IMPORTANT IMPORTANT**************** If the container ever asks you for a password (e.g. to install something) try typing in
systemsRcool. It may not show the password as you type it, that is normal. ********IMPORTANT IMPORTANT IMPORTANT****************
FAQ’s
Q1. I am encountering an “possibly corrupted debugging file” error when using Valgirnd, how can I fix this?
A: execute the following command in your Docker Container:
apt update -y && apt autoremove -y --purge clang clang-format && apt-get install -y lsb-release && apt-get install -y gnupg && apt-get install -y software-properties-common && wget https://apt.llvm.org/llvm.sh && chmod +x llvm.sh && sudo ./llvm.sh 19 && rm llvm.sh
Afterwards, recompile your program using make -B. You only have to do this once.
Q2. I am running into an “docker: invalid reference format.” error when running
docker run -td --user moya -v "${PWD}":/home/moya/shared -p 4096:4096 --name moya-container tqmcgaha/docker-env:moya
how can I fix this?
A: Run the following command
docker run -td --user moya -v "${PWD}:/home/moya/shared" -p 4096:4096 --name moya-container tqmcgaha/docker-env:moya