Installing the Virtual Machine at Home

Last updated: Aug 5, 2024

Overview

To set up our virtual machine on your own device:

Download Ubuntu and VirtualBox (or UTM)
Create a virtual machine running Ubuntu
Customize the Ubuntu installation
Install Ruby and Rails on the virtual machine
Install VS Code on the virtual machine

Questions?

See the troubleshooting guide for solutions to some common problems.

Step 1: Download Ubuntu and VirtualBox (or UTM)

Your machine's architecture determines which Ubuntu version (AMD64 or ARM) and hosted hypervisor (VirtualBox or UTM) you should use.

All platforms except Apple Silicon Macs: Download Ubuntu 22.04 LTS Desktop (AMD64) and VirtualBox.
Apple Silicon Macs: Download Ubuntu 22.04 LTS Server for ARM and UTM.

Note: If you have an older home machine, try the Lubuntu distribution instead. The installation and configuration directions are virtually identical to Ubuntu, and the version numbering of the distributions is the same. While Lubuntu is more responsive (especially on older hardware), its user interface is more primitive.

Step 2: Create a Virtual Machine Running Ubuntu

Follow one of version (a) or (b), below, depending on your hardware.

2(a): If you are using VirtualBox

Run VirtualBox and select Machine > New… to open the VM creation wizard. Then use the following values as you work through the wizard:

Name	Something of your choosing (e.g., 3901vm)
Type	Linux
Version	Ubuntu (64 bit)
Memory size	at least 4 GB (recommend about 1/2 of your machine's installed RAM)
Hard drive	Create a virtual hard disk now
Hard drive file type	VDI
Storage on physical hard drive	Dynamically allocated
File size	32 GB, or more (the suggested value may be too small)

Install Ubuntu on the new virtual machine. First start the newly created machine (Machine > Start), then select the Ubuntu ISO file downloaded in Step 1 as the start-up disk. As Ubuntu boots up for the first time, use the following responses:
1. Select "Install Ubuntu" (not "try")
2. Select "Normal" in both "Download updates" and "Install third-party software"
3. Select "Erase disk and install Ubuntu" (don't worry, it's the virtual machine's hard disk that will be erased!)
4. Enter your name (e.g., Jane Doe), a computer name (e.g., helium) a username (e.g., jdoe), and password
5. Restart (When prompted to "please remove installation media", just hit enter)
Configure the virtual machine to make it easier to work with.
1. Install "Guest Additions" in the virtual machine.
  1. After logging in to the virtual machine, open a terminal (Ctrl + Alt + T). Type the following command (the "$" is the command prompt, don't type that!)
```
$ sudo apt install gcc g++ make
```
  2. Use the top menu of the Virtual Box window to select Devices > Insert Guest Additions CD image…
  3. Click Run to allow the inserted CD to auto-run. Aside: If the CD does not auto-run (e.g. on Lubuntu), you can run the installer yourself by openning the CD in the file manager, then using Tool > Open Terminal to open a terminal in the CD's directory. In that terminal, run the installer:
```
$ sudo sh ./VBoxLinuxAdditions.run
```
  4. After the installation completes, eject the CD.
2. Enable cut-and-paste between host and VM. In the same Virtual Box VM menu, click Devices > Shared Clipboard > Bidirectional. This setting lets you cut-and-paste commands from host to VM (eg commands in this browswer window to your VM terminal).
(optional, only for newer host machines) Enable 3D acceleration. First shut down the virtual machine (click the power icon in upper right corner, then Shut Down…), then from the Virtual Box Manager window click Settings > Display > Enable 3d acceleration.
If your VM is sluggish, you might get better perfomance by allocating more processors. First shut down the virtual machine, then from the Virtual Box Manager window click Settings > System > Processor > choose 2 or more.

2(b): If you are using UTM

Run UTM and click the "+" button to open the VM creation wizard. Then use the following values as you work through the wizard:

Start	Virtualize
Type	Linux
Linux > File Imported	Browse to select the Ubuntu ISO downloaded previously
Memory size	at least 4 GB (recommend about 1/2 of your machine's installed RAM)
Drive space	32 GB, or more (the suggested value may be too small)
Mount directory	skip

Install Ubuntu on the new virtual machine. Use the run button to start the VM. Go through the Ubuntu Server installer. If the reboot fails, you can manually quit the VM, unmount the installer ISO, and start the VM again to boot into your new installation.
Configure the virtual machine to make it easier to work with.
1. Ubuntu Server only has a terminal interface. Install a desktop by logging in to the virtual machine and typing the following command (the "$" is the command prompt, don't type that!)
```
$ sudo apt install ubuntu-desktop
```
2. Enable cut-and-paste between host and VM.
```
$ sudo apt install spice-vdagent spice-webdavd
```

Step 3: Customize the Ubuntu Installation

The account you created in the previous step has administrator privileges, which allows you to do the customizations described below.

Note: A terminal window can be openned using the keyboard shortcut Ctrl + Alt + T.

Open a terminal and update the distribution by typing the following commands:
```
$ sudo apt update
$ sudo apt upgrade
$ sudo reboot
```
Install some useful linux tools:
```
$ sudo apt install git curl
```
Create an SSH private-public key pair to facilitate logging in to remote machines without typing a password. Copy the command below, customizing login@hostname with your own information.
```
$ ssh-keygen -t ed25519 -C "login@hostname"
```
When prompted, accept the default location (~/.ssh/id_ed25519) and default passphrase (i.e., empty for none).

Step 4: Install Ruby and Rails on the Virtual Machine

Install rbenv as well as ruby-build (a useful rbenv plugin). Both steps are accomplished via the rbenv-installer script:
```
$ wget -q https://github.com/rbenv/rbenv-installer/raw/HEAD/bin/rbenv-installer -O- | bash
```
After installation, reload the terminal for the changes to take effect.

Install Ruby.

# first install some Ruby dependencies
$ sudo apt install zlib1g-dev build-essential libssl-dev \
    libreadline-dev libyaml-dev libsqlite3-dev sqlite3 \
    libxml2-dev libxslt1-dev libcurl4-openssl-dev \
    software-properties-common libffi-dev
$ rbenv install 3.3.3 # this step takes several minutes
$ rbenv global 3.3.3  # set default ruby version
$ ruby -v # confirm it works

Install Rails.

$ gem install --no-document rails -v 7.0.8

Confirm Rails installation with a simple smoke test.

$ mkdir rails_work
$ cd rails_work
$ rails new demo
$ cd demo
$ rails server

The output of the last command should look something like:

=> Booting Puma
=> Rails 7.0.8.y application starting in development 
=> Run `bin/rails server --help` for more startup options
Puma starting in single mode...
* Puma version: 5.6.8 (ruby 3.3.3-pxx) ("Birdie's Version")
*  Min threads: 5
*  Max threads: 5
*  Environment: development
*          PID: 18440
* Listening on http://127.0.0.1:3000
* Listening on http://[::1]:3000
Use Ctrl-C to stop

You can kill the server with Ctrl-C (in the terminal window in which it is running):

^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: yyyy-mm-dd hh:mm:ss -0400 ===
- Goodbye!
Exiting

Install Node (not needed for Rails, but we'll be using it too).

$ wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
$ source ~/.bashrc
$ nvm install 20 --lts

Step 5: Install Chrome and VS Code on the Virtual Machine

(Optional) Install Chrome. (This step is optional because Ubuntu comes with Firefox, which is also fine for web development.)

$ wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
$ sudo apt install ./google-chrome-stable_current_amd64.deb

Install VS Code.
1. Download and install VS Code for linux.
2. Watch the first few overview videos to learn your way around the IDE.
3. Install some useful extensions: