Multipass runs on Linux, macOS, and Windows, although there are alternate options for
windows using WSL2 which you may prefer. Follow the instructions for installing Multipass for
your desired OS. It is not necessary to use the virtualbox driver.
If you prefer to use WSL2, there are instructions for setting up located here.
Multipass makes it very easy to launch a vanilla Ubuntu 20.04 instance (the version of linux you
are requied to standardize on). It is entirely possilbe that you will end up wanting different
resource levels at some point during the semester, so don't worry about picking the exact right
values for now. You can always delete and create a new instance easily if it's necessary. That
being said, a reasonably safe set of parameters is:
CPUs: 4
Mem: 8G
Disk: 20G
To launch this, you would execute:
multipass launch -n gameai -c 4 -m 8G -d 20G . Depending on your network
connection speed and how fast your computer is, this command may take a few minutes to
complete. When this command is completed, you can see if the machine is running using
multipass list . You should see an output that looks something like:
Name State IPv4 Image
primary Running 192.168.64.2 Ubuntu 20.04 L
TS
Please note, the name of the running VM in this sample output is primary , not gameai as
you would expect to see if you copied the exact command from above. Make note of the IP
address, as you will need this to connect to the running VM and enable X11 forwarding (which is
Instructions for Setting Up Ubuntu Multipass
Installing Multipass
Launching your instance
necessary for displaying SFML windows).
If you're like me and are using primary as the name of your VM, then Multipass will
automatically mount your home directory from your host machine in the Home directory of
your virtual machine. If you aren't using primary, you will need tell the VM to mount your code.
you can accomplish this via the multipass mount command, which takes two arguments:
source and target . The source is the path to the directory you want to mount, and
the target is the name of the instance and directory you want it mounted to (e.g.,
gameai:/home/ubuntu/gameai ).
Note: This section is written assuming the name of your VM is gameai . If you chose
something different, please modify commands accordingly.
Multipass makes it very easy to run commands inside your VM with the
multipass exec gameai command. You can get a bash shell by running
multipass shell gameai . However, in order to enable port-forwarding which we'll need
to display windows, you will want to ssh to your VM using the IP address obtained from
multipass list .
You will need to create a ssh keypair if you don't already have one. (Please google for directions
based on the ssh client you are using). You need to copy the ssh public key into the VM and
add it to the authorized_keys file.
multipass transfer ~/.ssh/id_rsa.pub gameai:.ssh/id_rsa.pub
multipass shell gameai
cd .ssh/
cat id_rsa.pub >> authorized_keys
rm id_rsa.pub
exit
If you're on a mac and using XQuartz (best to install it using homebrew, visit brew.sh for
installation instructions for homebrew, then execute brew install xquartz ), you will
need to start XQuartz before opening your terminal to make sure your $DISPLAY
enviroment variable is set. Check that your display environment variable is set by using
echo $DISPLAY on the host.
Now, you should be able to connect to the running VM and forward X11 connections. In this
example, it would be:
Connecting to your VM
ssh -Y ubuntu@192.168.64.2
As a general rule, it's a good idea to keep your software up to date, so after initial launch (and
periodically throughout the semester) I recommend running
sudo apt update && sudo apt -y upgrade in your VM. Then, to verify you are able
to display X11 apps on your host, run this in your VM:
sudo apt install x11-apps
xeyes
You should see a pair of eyes appear in a window that follow your mouse pointer around.
SFML uses OpenGL, and out of the box there can be some issues getting it to work. Thankfully,
they are solvable in a few easy steps.
The first error has to do with an OpenGL profile. The easiest fix for this is to add
export LIBGL_ALWAYS_INDIRECT=1 to your ~/.bashrc and then reload it with
source ~/.bashrc . That change will persist.
The more significant challenge with XQuartz is glx forwarding. If you're using an older version of
XQuartz, please update to a recent version. I tested with 2.8.1 and it worked. Next, you will need
to tell XQuartz to enable iglx. This is done on the host (macOS) with the defaults command
defaults write org.xquartz.X11 enable_iglx -bool true . You can verify the
output with:
defaults read org.xquartz.X11
{
SUHasLaunchedBefore = 1;
SULastCheckTime = "2022-01-17 20:07:31 +0000";
"app_to_run" = "/opt/X11/bin/xterm";
"cache_fonts" = 1;
"done_xinit_check" = 1;
"enable_iglx" = 1; #### <---- THIS IS THE IMPORTANT LINE
"login_shell" = "/bin/sh";
"no_auth" = 0;
"nolisten_tcp" = 1;
"startx_script" = "/opt/X11/bin/startx -- /opt/X11/bin/Xquartz";
}
Overcoming OpenGL issues
A few caveats:
1. Apple's defaults command are user-specific, so if you run the defaults command as root but
run XQuartz as a regular user it will not work.
2. If you're using an earlier version of XQuartz and don't want (or are unable to upgrade), the
defaults are located in a different place. You will need to research for your specific version
number if you are not running XQuartz vs. 2.8.1 or greater.
Once iglx is enabled, you will need to restart XQuartz. Test things are working by connecting to
your Multipass VM using the ssh method described above, and run the glxgears command.
If it is working, you should see a window appear with three colored gears rotating.
Once you have the base system installed and running, we will need a few libraries. Note: these
are the only libraries we will have installed for grading, so please follow these steps
exactly. In your VM, run:
sudo apt -y install build-essential libsfml-dev
Library Installation