Assignment #0: Getting Access to a Linux platform

Several assignments in this course require that you use a Linux platform. This “assignment” guides you through the steps you need to follow to set up your own Linux environment. Note that Having some experience with Linux is crucial for your professional prospects. Almost every back-end system out there runs Linux. So if you’re not familiar with Linux, don’t think of this “Linux for ICS332” as just something you have to do, but as a valuable experience. Each semester I get e-mails from alumni saying either “I wish I had been better at the command-line before getting my first job” or “I am so glad I was good with the command-line before hitting the job market”.

If you encounter difficulties here, do not hesitate and contact the instructor/TA!

I. Getting Access to a Linux platform

If you’re already running Linux in one way or another that you like and are comfortable with, you can skip to the Installing Java below.

Otherwise, here are some options:

• Option #1 Use a Docker image [RECOMMENDED APPROACH]
• Option #2 If you are using Windows 10, use WSL2 to run and install Ubuntu
• Option #3 Get a Linux Virtual Machine on the cloud (e.g., using AWS)
• Option #4 Use uhunix.hawaii.edu [WARNING: Some assignment may require superuser privileges, which you won’t have on this machine]
• Option #5 Install a terminal-only Linux Virtual Machine using Vagrant [WARNING: Students have experienced problems with Vagrant on M1/M2 Apple processors]

• Option #6 Install a Linux Virtual Machine using Virtual Box [WARNING: Students have experienced problems with VirtualBox on M1/M2 Apple processors]

• Option #7 Install Linux on your own system

Some of these options are easier/harder and have different advantages. When in doubt ask your instructor/TAs.

The instructor for this course recommends and uses Option #1.

Option #1: Use a Docker image

If not already installed on your system already, install Docker. I’ve prepared a Docker image called henricasanova/ics332 that you can use from the command-line.

The idea is that you keep your source files on your host in some working directory. In that same directory, you simply type the following command (This can take a long time the first time):

On Linux or MacOS:

docker run -it --rm --name mycontainer -v "`pwd`":/home/ics332user henricasanova/ics332 /bin/bash

or on Windows using the CMD prompt:

docker run -it --rm --name mycontainer -v "%cd%:/home/ics332user" henricasanova/ics332 /bin/bash

or on Windows using PowerShell:

docker run -it --rm --name mycontainer -v "${pwd}:/home/ics332user" henricasanova/ics332 /bin/bash

The pwd/cd stuff above it to say “the current working directory”. Of course you can use any path there so that the content at that path is visible on the Linux machine in the /home/ics332user/ directory.

This will give you a command-line terminal (or shell) inside a Linux container, and in the working directory on the container you will have access to the content of your working directory on your host. When you log out of the container, it terminates.

In a second (or third, or fourth, …) terminal on your host in that same working directory, you can type:

docker exec -it  mycontainer /bin/bash

This command will also open a command-line prompt inside the Linux container.

Bottom-line: you can develop your code on your host and compile/run it on the container.

Skip Section II (Installing Java) below. You are Done

Your container runs slowly? On your machine, you may find your container run slowly (for instance, if you have an M1/M2 Apple processor). In this case you may want to build the image locally. To do so, follow the following steps:

• On some directory on your computer, doesn’t matter where, download this Docker file.
• In that directory, on the command-line, type the following command:

docker build --no-cache -t henricasanova/ics332 .

(don’t forget the . above at the end of the line!)

Option #2: Run Ubuntu via WSL2 on Windows 10

WSL2 supports 32-bit binaries. See these two links.

• WSL2 vs. WSL1
• WSL2 description, which mentions 32-bit binaries

So, as long as you have the latest Windows and WSL2, you should be all good, and proceed to Step II below.

Option #3: Get a Linux Virtual Machine on the cloud (e.g., using AWS)

WARNING: Some assignment may require superuser privileges, which you won’t have on this machine

Plenty of information on-line on how to do this!

Option #4: Use uhunix.hawaii.edu

You all have an account on uhunix.hawaii.edu (using your UH username and password), which runs Linux.

Option #5: Run Terminal-only Linux using Vagrant

WARNING: People have encountered problems on M1/M2 Apple processors with this option. Try at your own risk!

Vagrant is a great tool that sits on top of virtualization frameworks and allows for super quick installation and usage. I use it on top of Virtual Box, which is free. The Getting Started page on the Vagrant Web site is really good, but just in cases here are a few easy steps:

• Download an install Virtual Box (but don’t do any kind of VM setup… just install the software)
  • On Mac you may get an error “The installation failed”. This is to be resolved by allowing Oracle applications to be downloaded in the Security & Privacy section of System Preferences.
• Download and install Vagrant
• Create a directory someplace convenient, say my_vagrant, and cd to that directory
• In that directory, using whatever terminal on your system, type the command: vagrant init ubuntu/bionic64
  • If you’re a Windows user, here is a likely helpful site about Vagrant and Windows
• Then type the command: vagrant up
  • On Windows (on an AMD processor) you may get a “There was an error…” message with in particular the message “VBoxManage.exe: error: AMD-V is disabled in the BIOS…”. In this case, you need to go into the BIOS settings and search for the “SVM Mode” setting,m which you need to enable before running vagrant.
  • On Windows (on an Intel processor) you may get a “There was an error…” message with in particular the message “VBoxManage.exe: error: AMD-V is disabled in the BIOS…”. In this case, you need to go into the BIOS settings and search for the “VT-x” setting,m which you need to enable before running vagrant.
  • Another reason for the above problems is that Window’s Hyper-V must be disabled (Control Panel -> Program And Features -> Turn Windows Features on or off).
• After a few minutes, your VM is running, but you’re not “in” it
• To get a terminal to your VM: vagrant ssh, and voila, welcome to your Linux VM
• Once you log out from the VM, you can shut it down with: vagrant halt

Try out the above to make sure everything works. This is the most basic use of Vagrant. Your notice that once you’ve done all the above, you’ll have a file called Vagrantfile, which you can customize later if you want. The Vagrant site has tons of good information about additional capabilities and features. Remember that you must always be in your my_vagrant directory.

A very useful feature is that your my_vagrant directory on your host is mounted as /vagrant/ on your VM! So the files you keep there (i.e., your programming assignments) are visible both on your host (e.g., for editing) and on your VM (e.g., for compiling/running). In addition, if your VM may become compromised, you can always re-install from scratch but you haven’t lost your files since they’re always on your host! Note that this is /vagrant on the VM, that is a directory at the root (not, for instance, /home/vagrant, which is your home directory on your VM.

So, for instance, say you have your homework assignment on your VM in your home directory, and that it is in a directory called my_homework. This is how you would create a .tar archive and copy it to your host (i.e., your own computer):

% ls
my_homework/

% zip -r my_homework.zip my_homework

% cp my_homework.zip /vagrant

And now, on your computer, in the same directory in which you typed vagrant ssh you’ll see that file my_homework.tar has magically appeared.

Option #6: Run GUI-enabled Linux using Virtual Box

WARNING: People have encountered problems on M1/M2 Apple processors with this option. Try at your own risk!

Vagrant above gives you very basic Terminal access, which is fast. However, perhaps you want a full-features Ubuntu GUI, at the risk of it running slowly on your system. In this case, you want to use Virtual Box (or whatever Virtualization framework you want/have installed), and create and start your VM that way. There are plenty of on-line documentation/tutorials on how to install Ubuntu on VirtualBox. You should get the 17.04 Ubuntu desktop distribution, which you can get from the UH mirror (e.g., download the file named ubuntu-16.04-desktop-i386.iso.)

You absolutely want to set up a Shared Folder (which works as the /vagrant/ directory in Option #3). This way, the files you keep there (i.e., your programming assignments) are visible both on your host (e.g., for editing) and on your VM (e.g., for compiling/running). In addition, if your VM may become compromised, you can always re-install from scratch but you haven’t lost your files since they’re always on your host!

Option #7: Run Linux on your own system

This is of course the slam dunk. Many of you are already running Linux and can likely stop reading now. Running Linux on your own machine is of course the ultimate way to gain experience, and most people get started with the ever so popular Ubuntu desktop distribution.

If you’re not quite ready to replace your current OS with Linux, you can go dual boot by installing a Linux partition on your machine. This is pretty standard, and there are many step-by-step guides on-line. A decent one for setting up a dual-boot Windows/Linux machine is on the Ubuntu Web site. Ubuntu also provides a Windows installer, which I’ve never tried myself but has been used successfully by many people. See this page for MacOS/Ubuntu dual boot. These links are active but may be stale. Web search engines are your friends for figuring this out.

II. Installing Java

If you are using the Docker image (Option #1 above) you can skip this step as Java is already installed on that image, and you are done!

Now that you have access to a Linux machine, you need to install Java. But perhaps Java is already installed! Try to invoke the Java compiler from the command-line as follows:

javac -version

If you get some output like “javac XX…” where XX is 8 or above, you’re all set can skip everything below. (If you get this output but where XX is below 8, then you need to upgrade Java to at least OpenJDK 8 - unlikely.)

If you get some “command not found” error message, then follow the steps below to install Java.

Assuming you’re running Ubuntu, you can use the Ubuntu package manager tool with a GUI. However, I typically use only the command-line (you’ll find that’s a theme throughout the semester) to install packages.

First, make sure you are connected to the network. Then on your Linux system type the following command in the Shell:

sudo apt update

The sudo command runs commands as the super user, and when you installed Ubuntu you were placed by default in the list of users who can use sudo. The apt command is used to deal with everything related to package management, and in the invocation above, to update your package list so that you will not have errors installing new packages. This could take a while.

Once the package list has been updated, then install Java (OpenJDK) by typing the following command:

sudo apt install default-jdk

Once this is done, you should be able to invoke javac -version from the command-line and get the expected output.