Lab 1: Docker

Docker is a system for running virtual computers inside your real computer. We are using Docker so that all students can run the same Ubuntu Linux lab environment, regardless of what computer they own.

The virtual computers that Docker runs are called containers. A container is based on a read-only template called an image, which contains the operating system, files etc. that are present when the container starts. We will be using an image based on Ubuntu for the CITS2003 labs.

We will be installing Docker using Docker Desktop. This is an easy-to-install package that includes a Docker daemon and client (both GUI and command line client). The Docker daemon runs in the background, and we will use the command line Docker client to perform Docker commands such as launching containers. The GUI client is not much use to us. For more information on what Docker is, see Lecture 2: Docker.

Installation

1. OS-specific prep

Follow the steps for your Operating System.

Windows

Windows Subsystem for Linux (WSL) is a prerequisite for running Docker on Windows. If you have not already installed WSL, install it now. Please follow the official Microsoft instructions. It is likely that Ubuntu 22.04 will be default version. If not, use the Microsoft installation instructions to choose that version. If version 22.04 is not yet supported, 20.04 is also fine, for our purposes.

Troubleshooting

There are several things that can go wrong with your WSL install:

• You can't find cmd.exe or Powershell:
1. Powershell can be installed from the Microsoft Store
2. You may be running in Windows S mode that will prevent you running and installing apps. To turn off Windows 10 S Mode, click the Start button then go to Settings > Update & Security > Activation. Select Go to the Store and click Get under Switch out of S Mode.
• You encounter problems installing WSL 2:
1. Follow the official Microsoft instructions.
2. Read the official Docker instructions.
3. If you installed WSL on an older version of windows and you got a Docker failed to initialise error, see step 4 here.

Mac (Intel x86)

You can check what chipset your machine uses by clicking on "About this Mac" in the Apple menu (top left of the screen). If your Mac is more than a couple years old you probably have an Intel x86 Mac. There are no additional steps for this system.

M1 Mac (ARM)

If you have a new Mac (purchased in the last year or two), you may have an M1 mac. M1 Mac uses a different chip-set to Intel Macs, so it cannot directly run code based on the Intel x86 chip-set. However, it can run programs built for Intel using an emulator called Rosetta 2.

If you have not already installed Rosetta 2, install it now:

1. Open the Terminal app
2. Run the following command:

   /usr/sbin/softwareupdate --install-rosetta --agree-to-license



2. Download and install Docker

Download the correct installer from https://www.docker.com/get-started. Follow the steps in the installer to install Docker Desktop.

If you want to read the official installation instructions, you can find them here.

Run Docker

Start Docker Desktop

Congratulations, you have installed Docker! Run Docker Desktop (if you haven't already) to start the Docker Service.

Once Docker Desktop opens, you should see a little whale icon on your taskbar showing that the Docker daemon is running. If this ever goes away, you can restart it by opening Docker Desktop again. Go ahead and close Docker Desktop: the daemon will keep running in the background.

Warning: don't use Docker Desktop to launch your docker images. It gives you a weird prompt and won't automatically stop the image when you log out. This is a recipe for confusion, so stick to the command line!

Help, my Docker on Windows had a "failed to initialise" error!: you probably failed to install WSL properly, go back to the windows WSL troubleshooting steps

Open a terminal

Windows

• Note: if you see C:\Windows\System32 when you open the terminal, you are in a useless location where you will need admin priveleges to do anything (did you open the terminal as administrator by mistake?). Before continuing, navigate to a safe place like your home directory: cd C:\Users\dan (of course your username will be different to mine)
• Note: if you want a prettier terminal, you can install "Windows Terminal" from the Windows Store. You can then open a Command Prompt or Powershell inside Windows Terminal.
• Note: do not use WSL as your prompt for launching Docker.

Mac

Download the Docker image

Once the Docker daemon is running, we can use the Docker client to perform Docker commands. Start by downloading the Docker image for the labs:

docker pull mjw263/osts_2023:v1

docker pull downloads a Docker image from a repository (Docker hub by default). The image we are pulling is owned by a user called mjw263, the image name is osts_2023, and we are pulling the tag (version) v1.

Create a directory on your host machine

It's time to create a directory (folder) to store your lab work. We also need the absolute path of this directory so that we can mount it into a container. The steps to do this vary slightly depending on your OS:

Windows

mkdir osts

cd osts

cd

pwd

Depending on where you created the directory, your path should look something like this: C:\Users\dan\osts

Mac

mkdir osts

cd osts

pwd

Depending on where you created the directory, your path should look something like this: /Users/dan/osts

Launch the container

Once you have the absolute path for your osts directory, you can run docker. Copy the command below and replace the source value ("/Users/dan/osts" in the example) with your own osts absolute path from the previous step:

docker run -it --mount type=bind,source="/Users/dan/osts",target=/home/stud/perm mjw263/osts_2023:v1

After you run this command, you will notice that your command prompt changes to something like stud@763d8b5ed6f2:~$. This means you are inside the Docker container! Inside the container, your username is stud, your machine (the container id) is a gibberish number like 763d8b5ed6f2 and your location is ~. This container is running Ubuntu Linux, so all the shell commands from the lectures will work in here.

To exit the container, use the exit command. If you prefer, you can press Ctrl+D instead to log out. You will notice that your prompt returns to normal once you log out. When you log out or close the terminal window, the container stops.

docker run explained

There's a lot going on in this command, so let's break it down.

docker run: run a new container based on an image.

-it: Run the container as an interactive terminal (so that we can log into it and run commands).

--mount type=bind,source="/home/dan/osts",target=/home/stud/perm: Mount a directory (/home/dan/osts) on your host computer to /home/stud/perm inside the container. All files in this directory are shared between your host machine and the container. This is important because Docker containers are stateless, meaning that when you log out, the Docker container stops and all files in it are deleted. The next time you call docker run it will create a fresh container based on the image and it will not recover any files from the last container you had. Only the shared files are preserved, because they are copied onto your host computer.

mjw263/osts_2023:v1: The owner, name and tag of the Docker image that the container is based on. Note that if you forget to docker pull an image before trying to docker run it, the run step will download it for you anyway.

Warning: Remember, Docker containers are stateless! This means that all files stored inside the container will be lost forever when you log out. Only the mounted directory will be preserved, so make sure you save all your work in the mounted directory.

Questions

1. Log into the lab container and navigate to the directory /lab/week1. Print the contents of the file you find there.
2. What does ~ mean in a file structure?
3. Navigate to your home directory in the lab container. You should see a directory called perm - this is the mounted directory. Create a directory inside perm called lab1. Copy the file from question 1 into lab1.
4. Open File Explorer (Windows) or Finder (Mac). Navigate to the osts directory you created earlier and open it. You should see the lab1 directory created in the previous question. Add any file to lab1 (a plain text file is recommended, but any file will do).
5. In your terminal window, list the contents of the lab1 directory. Can you see the file that you added in the previous step?
6. Besides these labs, name one application where you think Docker would be a useful tool.
7. Bonus: When might someone want to run Docker without the -it option?

Note: unless otherwise specified, all future labs will assume you are logged in to the lab container. Future labs will also not hold your hand when it comes to saving files. Remember to save your work in the mounted directory.

Department of Computer Science & Software Engineering The University of Western Australia Created By: Daniel Smith 8 February 2022 Last modified: 1 February 2023 Modified By: Michael Wise