Configuring VirtualBox with Ubuntu

(If useful, also covers using Docker)

This will enable teams to develop on Linux on their laptops, avoiding problems with connecting to services over a network. Many teams will stage their system on a remote server, but enabling local access

In this assignment will set up your computer to do C++ development with Docker and write tests in Unix. The directions assume you are using the school laptop with Windows installed. If you have a Linux system already set up and find that more convenient to use, you can use that as well. Mac OSX users might also be able to use the Unix on their system.

Warning: do not install Docker directly into Windows on your school laptop. Doing so will make it difficult, if not impossible, to use VirtualBox on the same system. This will make it difficult to complete other CS/SE courses. It can be very difficult to remove Docker once it is installed; we have stories of students having to reimage their laptops to remove it. (As of version 6 of Virtual Box there is some support for using Virtual Box with Hyper-V, but it is still highly possible that you will need to reimage your laptop to use VirtualBox in other courses.)

Note: to complete these steps, some Windows users at MSOE will need to turn on virtualization support in the BIOS. This is not an issue for macOS computers. If your MSOE laptop does not have virtualization support enabled, you will need to visit IT to have it turned on. This can be done at any point - you can install the software without virtualization, but some steps will fail. You may also need VT-x (that is, Intel Hyper-threading) to be enabled in the BIOS. See IT if you cannot access the BIOS yourself. In some cases you may need to disable Hyper-V in the Windows Feature list.

The following directions have you install Ubuntu, but you can use other variants of Unix. The primary advantage of Ubuntu over other Linux installs is that we have more experience with it.

Steps

  1. Download and install VirtualBox

    • Unless you are using a nonstandard operating system on your school laptop, you will want to download the Windows version.
    • Be sure to install all parts including the USB and Network Devices
    • Download and install the Oracle VM VirtualBox Extension Pack (available on the same page) after installing VirtualBox. This enables USB 2.0/3.0 and other features.

  2. Download Ubuntu22v3Cucumber.ova. You may have to log in to Box to access it. You can save it to a permanent folder, but running out of the downloads folder is fine, and you can delete the file once your Ubuntu system is running. This is a recent Ubuntu image with desktop support enabled. If you cannot access this image, you can install a different Ubuntu image instead; talk to me if you need help.

  3. Start VirtualBox and select Import Appliance... from the File menu. Browse to the Ubuntu image.

  4. To support copy/paste between the host and guest, right click on the imported virtual machine image (what VirtualBox calls the "appliance" in the previous step) and select Settings... Click on the Advanced tab and set both Shared Clipboard and Drag'n'Drop to Bidirectional. But note you will also need to an additional step below.

  5. In VirtualBox, use the menus to start the image. You will probably want to resize the window so it uses more of the screen.

  6. When Ubuntu starts up, log on as user osboxes using password "osboxes"
    If you wait at least five minutes and the password prompt is still not there - that is, the screen is blank - try halting the image and restarting it. If that doesn't work, you may have missed a step; it's important that all of the above steps are executed carefully. An ultimate fix is to uninstall VirtualBox, reboot your computer, and then reinstall it, following the above directions very carefully. Be sure you do not have Docker installed as a Windows application - it must be run from within a VM! If a reinstall does not help, talk to your instructor.

    • If you already installed Docker, you will need to uninstall it and visit this page for hints on cleaning up after Docker. In particular, you will need to disable Hyper-V{..="" docker-errors#hyperv""=""}. Some people report success by following this page instead.

  7. Once Ubuntu is running, click on the Devices menu and select Insert Guest Additions CD image... If nothing starts, open the CD image by opening it, right clicking on autorun.sh, and selecting Run as a Program. Go through the installation steps as indicated (selecting any defaults). You may have to shut down and restart the VM to enable copy/paste. You can right click on the .iso to eject it from your Ubuntu desktop.

  8. Explore Ubuntu. Some things to consider changing:

    • To change the timeout and reduce the number of times you have to enter the password, click on the machine control icon picture\nof multiple connected\ncomputers{width=“25px”} in the upper right corner, Settings, select the Power tab and select Never for when to blank the screen. You might also try turning off Automatic Suspend (both on battery power and when plugged in). Use the X in the upper right corner to close the window.
    • Open up a terminal prompt (see below) and change your password by entering the command passwd.

Using Docker on Ubuntu

  1. Press Ctrl-Alt-T to open a terminal window. This is also known as a command prompt. If you cannot remember the shortcut, or it does not work, click on the applications icon 9 dot\nicon{width=“25px”} in the lower left corner and enter "ter" in the search box. Terminal will be one of the results. Note the triple-bar menu has a way to increase font size.

  2. Confirm that Docker is installed and running:

    \$ sudo docker run hello-world

    If things are working, you'll get a message saying "Hello from Docker!" along with other information. If you don't, post your error to Teams and someone will help. The most common error is to not type the command exactly as written above; upper case or underscores instead of dashes will make things fail.

    • One simple thing to try if Docker is not working is to update Ubuntu. Open up the list of applications and run Software Updater. This will look for updates and attempt to install them. You can do the same thing from the command prompt by opening a Terminal window and typing

      \$ sudo apt update \$ sudo apt upgrade

      likely followed by a Linux reboot. However, Software Updater is more robust.

  3. Type

    \$ sudo docker ps -a

    to view the running Docker containers. Unless you have run hello-world more than once, you would likely see just one item. You can remove all of the docker containers by typing

    \$ sudo docker rm \$(sudo docker ps -aq)

    The docker ps -aq{.bw} command lists all running container ids, putting it between $({.bw} and ){.bw} substitutes those numbers on the command prompt, and docker rm deletes the named containers.

  4. Use Git to retrieve the code for this lab:

    \$ git clone https://hasker@bitbucket.org/hasker/cube

  5. Change the current directory to the newly created one:

    \$ cd cube

    Note you can type cd ..{.bw} to go "up" to the current directory's parent and cd ~{.bw} to go to your home directory.

  6. From the cube directory, type

    \$ sudo docker build ./

    to build the Docker container. This is controlled by the Dockerfile (you can click the link to view the file) which creates a container with version 18.04 of Ubuntu, installs G++, git, and GoogleTest, sets up GoogleTest, and copies the source files into the directory /cube in the Docker container. The nice thing is that if you repeat the build, Docker does not have to re-execute all of these steps, making it much faster. It will finish by building cube_test and running it; all test cases should pass.

  7. Modify the code so that the tests fail. To do this, you'll need an editor. One option is vi (sudo apt install -y vi), but most students will be happier with a mouse-based editor. I use Atom; this should be installed, but if not you can install it by

    \$ snap install atom

    If you are used to a different Unix editor, feel free to install and use that instead.

    Be careful! Make sure your modified code still builds and passes at least some of the tests. Syntax errors or errors that fail every test are not particular interesting ways to ensure your Docker environment can catch programming errors.

  8. If you type docker ps -a you will see that new containers have been created. Adding the --rm option to build will remove the containers when they are done.

  9. Revise the code so all tests will pass again and confirm that they do by typing

    \$ sudo docker build \--rm ./

Common Problems and Solutions

  • You get a blank screen when Ubuntu starts up. Sometimes this clears in several minutes; it pays to be patient. But this is also a symptom of having installed Docker directly on Windows (instead of in the Ubuntu VM); you will need to uninstall Docker to get VirtualBox to work for this and other courses.
  • The VM is not responding to mouse clicks. For example, you can open a Terminal window but cannot move it using the mouse. Try shutting down the Unix session ("ACPI Shutdown") and then completely shut down VirtualBox. On Windows, it seems necessary to reboot your computer. If that does not work, please contact me.
  • You get the message Unable to insert the virtual optical disk.../VBoxGuestAdditions.iso into the machine. This typically means the disk is already inserted; check for a disk icon in the Activities bar on the left hand side of the screen. If you see it, then it's already loaded.