From fb7f9a08ebf25a095802dcf9bab0b342f6f0d8b4 Mon Sep 17 00:00:00 2001 From: Justin Sadakhom <32400122+justin-sadakhom@users.noreply.github.com> Date: Wed, 5 Jun 2024 15:01:33 -0400 Subject: [PATCH] [Documentation:System] Improve Vagrant VM Install Docs (#591) - Change steps under "Submitty Developer VM Installation" to be H4 to create better separation between steps and sub-steps - Add instructions for how to disable virtualization in Windows 11 - Consolidate steps for downloading and installing dependencies into a single step to keep it short - Fix various grammar and formatting mistakes I had trouble following the installation steps as I was setting up the VM. These changes make the steps easier to read and more digestible. --------- Co-authored-by: Barb Cutler Co-authored-by: Barb Cutler --- .../vm_install_using_vagrant.md | 394 ++++++++++-------- 1 file changed, 214 insertions(+), 180 deletions(-) diff --git a/_docs/developer/getting_started/vm_install_using_vagrant.md b/_docs/developer/getting_started/vm_install_using_vagrant.md index 8876e846..89cc78a8 100644 --- a/_docs/developer/getting_started/vm_install_using_vagrant.md +++ b/_docs/developer/getting_started/vm_install_using_vagrant.md @@ -73,227 +73,264 @@ If you using an Intel-based Mac, you will follow the instructions below._ ## Submitty Developer VM Installation -1. Enable Virtualization +1. ENABLE VIRTUALIZATION + *Follow the instructions below specific to your host operating system:* + + * **MacOS** + *Virtualization is generally enabled by default.* + + * **Windows 10** + 1. Open the **Settings** app by searching for it in the windows bar or clicking it in the Windows menu. + 2. Navigate to **Update and Security**, then select **Recovery** from the side menu. + 3. Under **Advanced Startup**, click **Restart Now**. + 4. Once your PC has rebooted, click the **Troubleshoot** option. + 5. Click **Advanced Options**. + 6. Click **UEFI Firmware Settings** and restart as suggested. + 7. Enter your **BIOS** (generally by pressing Del, F12, or other keys while booting). + If you are not able to find the key combo needed to enter your BIOS, + refer to [this guide](https://www.tomshardware.com/reviews/bios-keys-to-access-your-firmware,5732.html). + 8. Locate **Virtualization**, and enable it. + (Note: Some motherboards may call it SVM, AMD-V, VT-x/Vanderpool. + If you cannot find the option to enable virtualization, + [search Google](http://tinyurl.com/enable-virtualization) for a tutorial on enabling it with your motherboard.) + 9. Reboot your computer. + + * **Windows 11** + 1. Open **Change advanced start-up options** by searching for it in the search bar. + 2. Under **Advanced Startup**, click **Restart Now**. + 3. Once your PC has rebooted, click the **Troubleshoot** option. + 4. Click **Advanced Options**. + 5. Click **UEFI Firmware Settings** and restart as suggested. + 6. Locate **Virtualization**, and enable it. + (Note: If you cannot find the option to enable virtualization, + [search Google](http://tinyurl.com/enable-virtualization) for a tutorial on enabling it with your motherboard.) + 7. Reboot your computer. + + * **Ubuntu** + 1. Enter your **BIOS** (generally by pressing Del, F12, or other keys while booting). + 2. Navigate the **BIOS Settings**. + 3. Locate **Virtualization** and enable it. (Some motherboards may call it SVM, AMD-V, VT-x/Vanderpool) + 4. Be sure to choose **Hardware Virtualization** in the **System -> Acceleration** + settings of the virtual machine you are using. + 5. **Note:** If using secure boot, Vagrant may fail to work with VirtualBox. + You will then either need to disable secure boot from the boot menu/BIOS or + follow [these steps](https://era86.github.io/2018/01/24/vagrant-virtualbox-secureboot-in-ubuntu-1604.html) + to self-sign the necessary packages to run Vagrant and VirtualBox. + +2. DOWNLOAD AND INSTALL THE LATEST DEPENDENCIES + + * You will need: + *Follow the instructions below specific to your host operating system* + + * [Ruby](https://www.ruby-lang.org/en/downloads) + * [Git](https://git-scm.com/downloads) + * [VirtualBox](https://www.virtualbox.org/wiki/Download_Old_Builds_6_1) + * [Vagrant](https://www.vagrantup.com) + + + * **MacOS** + You can either go to respective sites and download the necessary binaries or + install [Homebrew](http://brew.sh/), if you don't have it, and then run: - **MacOS** - 1. Virtualization is generally enabled by default. + ``` + brew install --cask virtualbox + brew install --cask vagrant + ``` - **Windows 10** - 1. Open the **Settings** app by searching for it in the windows bar or clicking it in the Windows menu. + * **Windows** + *You can just go to the respective sites and download the necessary binaries.* - 2. Navigate to **Update and Security**, then select **Recovery** from the side menu. - 3. Under **Advanced Startup**, click **Restart Now**. + * **Ubuntu/Debian** - 4. Once your PC has rebooted, click the **Troubleshoot** option. + * The Ubuntu repository does not contain the latest version of + Vagrant or VirtualBox and using them may not work nor are they + supported. We recommend that you either download the necessary + binaries from their respective steps or follow the steps + outlined below for each: - 5. Click **Advanced Options**. + VirtualBox: - 6. Click **UEFI Firmware Settings** and restart as suggested. + Vagrant: + (if that doesn't work, try: ) - 7. Enter your **BIOS** (generally by pressing Del, F12, or other keys while booting). If you are not able to find the key combo needed to enter your BIOS, refer to [this guide](https://www.tomshardware.com/reviews/bios-keys-to-access-your-firmware,5732.html). + * **Fedora/Red Hat Linux** - 8. Locate **Virtualization**, and enable it. (Note: Some motherboards may call it SVM, AMD-V, VT-x/Vanderpool. If you cannot find the option to enable virtualization, [search Google](http://tinyurl.com/enable-virtualization) for a tutorial on enabling it with your motherboard.) + * For Fedora, the latest version of VirtualBox is recommended to + prevent errors. Download the RPM from the VirtualBox + website. Make sure your version of Fedora is up to date using + ``` + sudo dnf update + sudo dnf upgrade + ``` - 9. Reboot your computer. + and inputting your password. Then install the Virtual Box rpm + using: + ``` + sudo dnf install VirtualBox-xxxxx.rpm + ``` - **Ubuntu** - 1. Enter your **BIOS** (generally by pressing Del, F12, or other keys while booting). + Install Vagrant using: + ``` + sudo dnf install vagrant + ``` - 2. Navigate the **BIOS Settings**. + * **Note:** + When running vagrant up, use `vagrant up --provider=virtualbox` so it doesn't default to libvirt - 3. Locate **Virtualization** and enable it. (Some motherboards may call it SVM, AMD-V, VT-x/Vanderpool) + * **Common errors when running vagrant up (Fedora/RHEL)** + + 1. Missing virtnetworkd: + Enable it in your terminal by running: + ``` + sudo systemctl start virtnetworkd + ``` + + 2. If your vagrant ever freezes kill it with + ``` + VBoxManage controlvm VM_NAME poweroff + ``` + or if that doesn't work, reboot the computer and then + run `vagrant destroy` before re-running `vagrant up --provider=virtualbox` again. - 4. Be sure to choose **Hardware Virtualization** in the **System -> Acceleration** settings of the virtual machine you are using. - **NOTE** - If using secure boot, vagrant may fail to work with VirtualBox. You will then either need to disable secure boot from - the boot menu/BIOS or follow [these steps](https://era86.github.io/2018/01/24/vagrant-virtualbox-secureboot-in-ubuntu-1604.html) - to self-sign the necessary packages to run vagrant and VirtualBox. +3. CLONE THE [SUBMITTY REPOSITORY](https://github.com/Submitty/Submitty) -2. Download and install the latest version of [Ruby](https://www.ruby-lang.org/en/downloads). + * Clone it to a location on your computer (the "host"). -3. Download and install the latest version of [Git](https://git-scm.com/downloads). + ``` + git clone https://github.com/Submitty/Submitty.git + ``` -4. Download and install [VirtualBox](https://www.virtualbox.org/wiki/Download_Old_Builds_6_1) and [Vagrant](https://www.vagrantup.com) - - **NOTE** - Please download VirtualBox 6 instead of 7. + **Note:** If you are not currently part of the Submitty organization on GitHub, you may want to + [fork](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) + the repo and use the git url from your fork instead, especially if you are looking to contribute. -Below are quick steps to get everything installed and running. + * _OPTIONAL: If you will be developing code in one of the companion + Submitty repositories (e.g., AnalysisTools, Lichen, + Localization, RainbowGrades, Tutorial), also clone those + repositories to the same directory. For example:_ - **Windows 10** + ``` + home + └── myusername + └── Submitty + └── GIT_CHECKOUT + ├── AnalysisTools (optional) + ├── Lichen (optional) + ├── Localization (optional) + ├── RainbowGrades (optional) + ├── Submitty + └── Tutorial (optional) + ``` - * You can just go to the respective sites and download the necessary binaries. + _This host directory structure will be shared / synced between + your host operating system and the Submitty virtual machine._ - **MacOS** - * You can either go to respective sites and download the necessary binaries or - install [homebrew](http://brew.sh/) if you don't have it and then run: +4. RUN VAGRANT - ``` - brew install --cask virtualbox - brew install --cask vagrant - ``` - - **Ubuntu/Debian** + If you have an AMD processor you can choose to download a pre-made + VM that is created weekly OR you can create the VM from scratch + (which will take substantially more time). If you have an ARM chip + (e.g., the Apple Silicon Mac M1/M2/M3), you must create the VM from + scratch. - * The Ubuntu repository does not contain the latest version of Vagrant or VirtualBox and using - them may not work nor are they supported. We recommend that you either download the necessary binaries - from their respective steps or follow the steps outlined below for each: + + * Navigate into the Submitty repository on your computer in a + shell/terminal. _On Windows, run CMD or PowerShell on administrator mode_. - VirtualBox: - Vagrant: - (if that doesn't work, try: ) + * **Build pre-packaged VM** - **Fedora/Red Hat Linux** + If you are using VirtualBox as your provider, you will by default + use a pre-packaged Submitty VM. This will have all of Submitty + already setup. Vagrant will build your VM for you. - * For Fedora, the latest version of VirtualBox is recommended to prevent errors. Download the RPM from the virtual box website. Make sure your version of - Fedora is up to date using - ``` - sudo dnf update - sudo dnf upgrade - ``` - and inputting your password. Then install the Virtual Box rpm using: ``` - sudo dnf install VirtualBox-xxxxx.rpm + vagrant up ``` - Install Vagrant using: - ``` - sudo dnf install vagrant - ``` - Now move on to step 5. - - **NOTE** - when running vagrant up, use `vagrant up --provider=virtualbox` so it doesnt default to libvirt - - **Common errors when running vagrant up(Fedora/RHEL)** - 1. Missing virtnetworkd: - Enable it in your terminal by running: - ``` - sudo systemctl start virtnetworkd - ``` - 2. If your vagrant ever freezes kill it with - ``` - VBoxManage controlvm VM_NAME poweroff - ``` - or if that doesn't work, reboot the computer and then run `vagrant destroy` before re-running `vagrant up --provider=virtualbox` again. - -5. Clone [the Submitty repository](https://github.com/Submitty/Submitty) to a location on - your computer (the "host"). - ``` - git clone https://github.com/Submitty/Submitty.git - ``` + *This process will take 10 minutes to maybe half an hour + depending on your internet connection speed.* - **NOTE:** If you are not currently part of the Submitty organization on Github, you may want to - [fork](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) - the repo and use the git url from your fork instead, especially if you are looking to contribute. - _OPTIONAL: If you will be developing code in one of the companion - Submitty repositories (e.g., AnalysisTools, Lichen, Localization, RainbowGrades, Tutorial), also - clone those repositories to the same directory. For example:_ + * **Build from scratch** + If you wish to run `vagrant up` from scratch, on Linux or Mac type: ``` - home - └── myusername - └── Submitty - └── GIT_CHECKOUT - ├── AnalysisTools (optional) - ├── Lichen (optional) - ├── Localization (optional) - ├── RainbowGrades (optional) - ├── Submitty - └── Tutorial (optional) + BASE_BOX=1 vagrant up + ``` + + Or on Windows, type: + ``` + SET BASE_BOX=1 + vagrant up ``` - _This host directory structure will be shared / synced between - your host operating system and the Submitty virtual machine._ - -6. Navigate into the Submitty repository on your computer in a - shell/terminal and type: - - _Windows should run CMD or powershell on administrator mode_ + *This process will take anywhere from 30 minutes to a few hours + depending on your internet speed.* - ``` - vagrant up - ``` - If you are using VirtualBox as your provider, you will by default use - a pre-packaged Submitty VM. This will have all of Submitty already setup. - Vagrant will build your VM for you. This process will take 10 minutes to - maybe half an hour depending on your internet connection speed. - When this command finishes, your VM is ready to use. + ***ADDITIONAL NOTE:** When the `vagrant up` command completes + successfully, you will be able to access the Submitty website + (instructions follow in the next section). The VM will continue + to run jobs in the background and consume a nontrivial amount of + CPU resources, while completing a backlog of autograding for a + dozen or more sample submissions for each of the more than 100 + users in the sample courses.* - If you wish to run `vagrant up` from scratch, on Linux or Mac type: - ``` - BASE_BOX=1 vagrant up - ``` - or on Windows, type: - ``` - SET BASE_BOX=1 - vagrant up - ``` - This process will take anywhere from 30 minutes to a few hours depending on your - internet speed. -7. When the `vagrant up` command completes successfully, you will be - able to access the Submitty website (instructions follow in the - next section). + * **Build without sample submissions** - The VM will continue to run jobs in the background and consume a - nontrivial amount of CPU resources, while completing a backlog of - autograding for a dozen or more sample submissions for each of the - more than 100 users in the sample courses. + If your development work *will not require sample assignment + submissions or autograding results*, you may prepend + `NO_SUBMISSIONS=1` to the previous command, which will skip the + creation of these sample submissions and their autograding and + decrease the time to complete installation. - On MacOS and linux, if your development work *will not require sample assignment - submissions or autograding results*, you may prepend - `NO_SUBMISSIONS=1` to the previous command, which will skip the - creation of these sample submissions and their autograding and - decrease the time to complete installation. - ``` - NO_SUBMISSIONS=1 vagrant up - ``` + * On Mac or Linux: + ``` + NO_SUBMISSIONS=1 vagrant up + ``` - On Windows `cmd`, you will have to first set the environment variable - `NO_SUBMISSIONS` to 1 which lasts for the session of that console, - then call vagrant up. + * Or on Windows using `cmd`: + ``` + SET NO_SUBMISSIONS=1 + vagrant up + ``` - ``` - SET NO_SUBMISSIONS=1 - vagrant up - ``` + Or on Windows using PowerShell, you will have to set the environment variable differently: + ```pwsh + $Env:NO_SUBMISSIONS=1 + vagrant up + ``` - On PowerShell, you will have to set the environment variable differently: + If you want to unset the variable later in `cmd`, you can do: + ``` + SET NO_SUBMISSIONS= + ``` - ```pwsh - $Env:NO_SUBMISSIONS=1 - vagrant up - ``` + Or in PowerShell: + ```pwsh + Remove-Item Env:\NO_SUBMISSIONS + ``` - If you want to unset the variable later in `cmd`, you can do - ``` - SET NO_SUBMISSIONS= - ``` + Similarly, you can check that the variable is set by doing: + ``` + SET NO_SUBMISSIONS + ``` - Or in PowerShell, - ```pwsh - Remove-Item Env:\NO_SUBMISSIONS - ``` + Or in PowerShell: + ```pwsh + $Env:NO_SUBMISSIONS + ``` - Similarly, you can check that the variable is set by doing - ``` - SET NO_SUBMISSIONS - ``` +5. AND YOU ARE DONE! - Or in PowerShell, - ```pwsh - $Env:NO_SUBMISSIONS - ``` -8. When the install has completed, you should see the message: + When the installation has completed, you should see the message: ``` ##################################################################### @@ -314,15 +351,14 @@ Below are quick steps to get everything installed and running. ##################################################################### ``` - *NOTE: There are times when the install will pause for a brief + ***Note:** There are times when the install will pause for a brief period with the message `Done`. This does not mean the install has ended, and the install should continue after a bit of time.* If you do not see this message due to an error or the installation - has frozen, check out: - - * [Installation Troubleshooting](/developer/troubleshooting/installation_troubleshooting) + has frozen, check out: + [Installation Troubleshooting](/developer/troubleshooting/installation_troubleshooting) --- @@ -340,14 +376,12 @@ Below are quick steps to get everything installed and running. (see the VM login & password info below) * You can test the submission, autograding, and viewing of the - grades details by uploading sample submissions from the Submitty - repository, located in one of these these directories: + grade details by uploading sample submissions from the Submitty + repository, located in one of these directories: - For the "tutorial" course: - + - The ["tutorial" course](https://github.com/Submitty/Tutorial/tree/main/examples) - For the "sample" course: - + - The ["sample" course](https://github.com/Submitty/Submitty/tree/master/more_autograding_examples) 2. When the VM is "up", you can connect from your host computer to the virtual machine via ssh. Windows users will need to install SSH @@ -412,7 +446,7 @@ Below are quick steps to get everything installed and running. * development * blank - *Note: The current semester is calculated by either using an `s` if in the month is < 7 else use `f` + **Note**: The current semester is calculated by either using an `s` if in the month is < 7 else use `f` and then take the last two digits of the current year. So April 2017 would be `s17` while September 2017 would be `f17`.* @@ -444,7 +478,7 @@ Below are quick steps to get everything installed and running. vagrant up ``` - NOTE: when resuming work, you may see this warning several times, + Note: when resuming work, you may see this warning several times, `default: Warning: Remote connection disconnect. Retrying.. .` These warnings are not harmful and can be ignored. @@ -507,7 +541,7 @@ Below are quick steps to get everything installed and running. where `$SUBMITTY_HOST` is a reference to the `Host` from the SSH config file. - **NOTE** + **Note:** Especially for mobile operating systems, make sure that your SSH client supports SSH port forwarding. On iOS, you will also have to enable location tracking for the client to keep the connection alive in the background. This has been tested with Blink for iOS and Termius for iOS (also available on Android, untested).