From 7f4b5c9422e78a197e32412aa977b08227b2b49b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A1tvik=20Karanam?= <89281036+skara9@users.noreply.github.com> Date: Mon, 5 Aug 2024 15:18:05 -0400 Subject: [PATCH 01/13] merge m-series docs with rest of installation --- .../vm_install_using_vagrant.md | 16 +- .../vm_install_using_vagrant_apple_silicon.md | 183 ------------------ 2 files changed, 11 insertions(+), 188 deletions(-) delete mode 100644 _docs/developer/getting_started/vm_install_using_vagrant_apple_silicon.md diff --git a/_docs/developer/getting_started/vm_install_using_vagrant.md b/_docs/developer/getting_started/vm_install_using_vagrant.md index 84bfbe62..4bbe4476 100644 --- a/_docs/developer/getting_started/vm_install_using_vagrant.md +++ b/_docs/developer/getting_started/vm_install_using_vagrant.md @@ -124,7 +124,7 @@ If you using an Intel-based Mac, you will follow the instructions below._ * [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) + * [VirtualBox](https://www.virtualbox.org/wiki/Download_Old_Builds_6_1) (or [QEMU](https://www.qemu.org) instead for M-series macOS) * [Vagrant](https://www.vagrantup.com) @@ -133,9 +133,9 @@ If you using an Intel-based Mac, you will follow the instructions below._ install [Homebrew](http://brew.sh/), if you don't have it, and then run: ``` - brew install --cask virtualbox brew install --cask vagrant - vagrant plugin install vagrant-timezone + brew install --cask virtualbox # if on Intel chip + brew install qemu && vagrant plugin install vagrant-qemu # if on M-series chip ``` * **Windows** @@ -234,7 +234,7 @@ If you using an Intel-based Mac, you will follow the instructions below._ 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 + (such as Apple M-series), you must create the VM from scratch. @@ -248,9 +248,15 @@ If you using an Intel-based Mac, you will follow the instructions below._ use a pre-packaged Submitty VM. This will have all of Submitty already setup. Vagrant will build your VM for you. + To create the virtual machine, run: ``` - vagrant up + vagrant up --provider=virtualbox ``` + Replace `virtualbox` with `qemu` if on M-series macOS. + + ***Note:** The vagrant up command provisions the virtual machine on the first run. + For subsequent runs, you do not need to append the `--provider` flag as the VM is + already created.* If you wish to use a specific version of the pre-packaged Submitty VM, on Linux or Mac type: ``` diff --git a/_docs/developer/getting_started/vm_install_using_vagrant_apple_silicon.md b/_docs/developer/getting_started/vm_install_using_vagrant_apple_silicon.md deleted file mode 100644 index dd7652da..00000000 --- a/_docs/developer/getting_started/vm_install_using_vagrant_apple_silicon.md +++ /dev/null @@ -1,183 +0,0 @@ ---- -title: Vagrant QEMU on Apple Silicon -category: Developer > Getting Started > VM Install using Vagrant -redirect-from: - - /developer/vagrant_qemu_arm_mac ---- - -Currently, VirtualBox does not have support for Apple ARM, and the -Vagrant configuration we use does not work on Apple Silicon Macs. -To get around this, you can use an alternate configuration with a -plugin for QEMU virtual machines. - -__Note__: These instructions are specifically for Apple Silicon -computers and will not work on any other system regardless of -architecture. - ---- - -## Requirements - -1. Make sure you have an Apple Silicon Mac running macOS Monterey -(12.4) or higher. - -2. Make sure you have at least 65GB of free space on your disk to -allocate for the virtual machine. - -3. The installation process may take upwards of an hour or more. -Make sure your computer is connected to a reliable power source and -stable network, and that it does not go to sleep or hibernate during -the installation process. - ---- - -## Pre-Installation Steps - -1. Enable SMB file sharing - - * Open **System Settings** and navigate to **Sharing** - * Turn on **File Sharing** and go to options - * Check "Share files and folders using SMB" - * Check the box next to your username - * Click Done - ---- - -## Installation - -1. Install [Homebrew](https://brew.sh/) - ``` - $ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" - ``` - Follow the prompts and continue with the installation process. - -2. Download and install [Vagrant](https://vagrantup.com/) and [QEMU](https://qemu.org/) - - Both of these packages are fairly simple to install with homebrew: - ``` - $ brew install qemu - - $ brew install --cask vagrant - - $ vagrant plugin install vagrant-timezone - - $ vagrant plugin install vagrant-qemu - ``` - Note: It is possible that you may need to install Rosetta before installing vagrant. Run the following command to install Rosetta: - ``` - $ sudo softwareupdate --install-rosetta - ``` - -3. Clone and open the Submitty repository - - Navigate to the parent folder you want to clone into and do - ``` - $ git clone https://github.com/Submitty/Submitty - - $ cd Submitty - ``` - - **NOTE:** If you are not part of the Submitty organization on - GitHub, you may want to first - [fork](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) - the repository and clone 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:_ - - ``` - home - └── myusername - └── Submitty - └── GIT_CHECKOUT - ├── AnalysisTools (optional) - ├── Lichen (optional) - ├── Localization (optional) - ├── RainbowGrades (optional) - ├── Submitty - └── Tutorial (optional) - ``` - - _This host directory structure will be shared / synced between - your host operating system and the Submitty virtual machine._ - -4. Start up Vagrant and provision the machine - - ``` - $ vagrant up --provider=qemu - ``` - - You may be prompted to enter your login username and password - to mount the SMB files. - - After the machine is provisioned, it will start to run the - Submitty installation. This process may take upwards of an hour - or more depending on your internet speed, so ensure your computer - does not go to sleep during it. - - If the installation process fails due to network issues or is - interrupted in some way, you may need to delete it and start - over from the beginning with: - ``` - $ vagrant destroy - - $ vagrant up --provider=qemu - ``` - -5. After the `vagrant up` command completes, the VM is started and - running in the background. - - 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. - - ``` - $ NO_SUBMISSIONS=1 vagrant up - ``` - -6. When the install has completed, you should see the message: - ``` - ##################################################################### - - INSTALLATION SUCCESS! - - .GGQGGGSlu - .GGGGGGGGGGGS - :llUGGGGGGGGGGGGGGGG - 'GGGGGGGGGGGGGGGGGGb . - %GGGGGGGGGGGGGGG~ ..GSGGG - GGGGGGGGGGGGGGSGGGGGGGGGG[ - ;GGGGGGGGGGGGp\ \ \GGGGGGGGL - !GGGGGGGGGGGGGGS\ \ \GGGGGG - GGGGGGGGGGGGGGGGG\ \ \9GGGG - %GGGGGGGGGGGGGGGS/ / /.GGG - %GGGGGGGGGGGGGS/ / /GGG - '%NNNNNNNNNNNNNNNNNN - ##################################################################### - ``` - - *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) - ---- - - -## Now you can continue with the regular development instructions... - -[Using your Submitty Developer VM](vm_install_using_vagrant#using-your-submitty-developer-vm) From 608eec61aeea8a98be29de9a472f99e6c276a414 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A1tvik=20Karanam?= <89281036+skara9@users.noreply.github.com> Date: Mon, 5 Aug 2024 15:57:27 -0400 Subject: [PATCH 02/13] remove link to arm mac docs --- .../developer/getting_started/vm_install_using_vagrant.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/_docs/developer/getting_started/vm_install_using_vagrant.md b/_docs/developer/getting_started/vm_install_using_vagrant.md index 4bbe4476..1e6f0318 100644 --- a/_docs/developer/getting_started/vm_install_using_vagrant.md +++ b/_docs/developer/getting_started/vm_install_using_vagrant.md @@ -21,14 +21,6 @@ instructions. --- -_IMPORTANT NOTE: If you are using an Apple Mac computer -with [Apple Silicon (e.g., M1 or M2)](https://support.apple.com/en-us/HT211814), -first released in late 2020, you will follow -the [Vagrant QEMU instructions](/developer/getting_started/vm_install_using_vagrant_apple_silicon). -If you using an Intel-based Mac, you will follow the instructions below._ - ---- - ## Pre-Installation Checklist 1. To develop with a Virtual Machine (VM), your computer should have From 48f04271b1deb75d2ceca48610ccaf66801b6e2e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A1tvik=20Karanam?= <89281036+skara9@users.noreply.github.com> Date: Mon, 5 Aug 2024 15:57:42 -0400 Subject: [PATCH 03/13] add instructions for enabling smb --- .../developer/getting_started/vm_install_using_vagrant.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/_docs/developer/getting_started/vm_install_using_vagrant.md b/_docs/developer/getting_started/vm_install_using_vagrant.md index 1e6f0318..6d9d0ab8 100644 --- a/_docs/developer/getting_started/vm_install_using_vagrant.md +++ b/_docs/developer/getting_started/vm_install_using_vagrant.md @@ -54,7 +54,13 @@ instructions. platform and prevent VirtualBox from working correctly. It is recommended to not install or use WSL2 alongside Virtualbox for now. -5. The complete installation process could take an hour or more. Make +5. If you're on M-series macOS, you will be using QEMU with SMB file sharing. + To enable this, open **System Settings** and navigate to **General > Sharing**. + Press the (i) button next to **File Sharing**, and in the popup window + click "Options...". Then turn on "Share files and folders using SMB" and + check the box next to your name in the list below. + +6. The complete installation process could take an hour or more. Make sure your internet connection is strong and consistent. You'll probably want to plug in your laptop power cord. Check your computer settings and make sure the machine does not hibernate or From f0f1ec3c307ae59a79bff2778f0fb05e4f52b65a Mon Sep 17 00:00:00 2001 From: Barb Cutler Date: Tue, 6 Aug 2024 14:51:15 -0400 Subject: [PATCH 04/13] Update vm_install_using_vagrant.md --- .../vm_install_using_vagrant.md | 112 +++++++++++------- 1 file changed, 66 insertions(+), 46 deletions(-) diff --git a/_docs/developer/getting_started/vm_install_using_vagrant.md b/_docs/developer/getting_started/vm_install_using_vagrant.md index 6d9d0ab8..d94e945c 100644 --- a/_docs/developer/getting_started/vm_install_using_vagrant.md +++ b/_docs/developer/getting_started/vm_install_using_vagrant.md @@ -14,10 +14,8 @@ Unix/Linux). The installation process will create a new Virtual Machine (VM) on your computer and the VM will use the Ubuntu GNU/Linux operating system. -__Note:__ We only officially support and test development using VirtualBox. -The instructions below are for VirtualBox. While alternatively using -VMWare should work, we have not tested this, and do not provide these -instructions. +***NOTE:** We only officially support and test development using VirtualBox for AMD +and Intel machines and QEMU for M-Series ARM MacOS machines.* --- @@ -43,24 +41,23 @@ instructions. backend, which will be slower and can cause instability in the VM. - **Note:** - This may stop programs like Docker Desktop and WSL 2 from + ***NOTE:** This may stop programs like Docker Desktop and WSL 2 from working. If these programs are essential to your workflow, consider looking up how to add a separate boot entry with "hypervisorlaunchtype" - set to "off" for use with VirtualBox. + set to "off" for use with VirtualBox.* - **Note:** - Installing WSL2 may also reconfigure your OS to use Hyper-V or Windows hypervisor + ***NOTE:** Installing WSL2 may also reconfigure your OS to use Hyper-V or Windows hypervisor platform and prevent VirtualBox from working correctly. It is recommended to not install - or use WSL2 alongside Virtualbox for now. + or use WSL2 alongside Virtualbox for now.* -5. If you're on M-series macOS, you will be using QEMU with SMB file sharing. +5. If you're on M-series ARM MacOS (e.g., M1, M2, M3), you will be using QEMU with SMB file sharing. To enable this, open **System Settings** and navigate to **General > Sharing**. Press the (i) button next to **File Sharing**, and in the popup window click "Options...". Then turn on "Share files and folders using SMB" and check the box next to your name in the list below. -6. The complete installation process could take an hour or more. Make +6. The complete installation process could take an hour or more and + will quite possiby fail if paused or interrupted. Make sure your internet connection is strong and consistent. You'll probably want to plug in your laptop power cord. Check your computer settings and make sure the machine does not hibernate or @@ -110,7 +107,7 @@ instructions. 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. + 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. @@ -122,18 +119,27 @@ instructions. * [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) (or [QEMU](https://www.qemu.org) instead for M-series macOS) + * M-SERIES ARM MacOS: [QEMU](https://www.qemu.org) + * EVERYONE ELSE: [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: + install [Homebrew](http://brew.sh/), if you don't have it, and then: + If you have an M-series ARM Mac, run: ``` brew install --cask vagrant - brew install --cask virtualbox # if on Intel chip - brew install qemu && vagrant plugin install vagrant-qemu # if on M-series chip + brew install qemu + vagrant plugin install vagrant-qemu + ``` + + Or if you have an older Intel-based Mac, run: + + ``` + brew install --cask vagrant + brew install --cask virtualbox ``` * **Windows** @@ -174,6 +180,7 @@ instructions. sudo dnf install vagrant ``` +DELETE * **Note:** When running vagrant up, use `vagrant up --provider=virtualbox` so it doesn't default to libvirt @@ -193,7 +200,7 @@ instructions. run `vagrant destroy` before re-running `vagrant up --provider=virtualbox` again. -3. CLONE THE [SUBMITTY REPOSITORY](https://github.com/Submitty/Submitty) +4. CLONE THE [SUBMITTY REPOSITORY](https://github.com/Submitty/Submitty) * Clone it to a location on your computer (the "host"). @@ -201,14 +208,15 @@ instructions. git clone https://github.com/Submitty/Submitty.git ``` - **Note:** If you are not currently part of the Submitty organization on GitHub, you may want to + ***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. + 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 + * **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:_ + repositories to the same directory. For example: ``` home @@ -223,57 +231,69 @@ instructions. └── Tutorial (optional) ``` - _This host directory structure will be shared / synced between - your host operating system and the Submitty virtual machine._ + *This host directory structure will be shared / synced between + your host operating system and the Submitty virtual machine.* -4. RUN VAGRANT - - 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 - (such as Apple M-series), you must create the VM from - scratch. +5. RUN VAGRANT * Navigate into the Submitty repository on your computer in a - shell/terminal. _On Windows, run CMD or PowerShell on administrator mode_. + shell/terminal. *On Windows, run CMD or PowerShell on administrator mode.* * **Build pre-packaged VM** + *NOTE: The pre-packaged Submitty VM is not (yet) + available for qemu / M-Series ARM Mac machines.* + 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. + use a pre-packaged Submitty VM. This will have all of Submitty + already setup. This is a recently built machine, + but it may be slightly older than the current + [main branch on GitHub](https://github.com/Submitty/Submitty). + - To create the virtual machine, run: + To create the virtual machine from the pre-packaged image, run: ``` vagrant up --provider=virtualbox ``` - Replace `virtualbox` with `qemu` if on M-series macOS. - - ***Note:** The vagrant up command provisions the virtual machine on the first run. - For subsequent runs, you do not need to append the `--provider` flag as the VM is - already created.* - If you wish to use a specific version of the pre-packaged Submitty VM, on Linux or Mac type: + If you wish to use a specific version of the pre-packaged Submitty VM, on Linux type: ``` - PREBUILT_VERSION={version} vagrant up + PREBUILT_VERSION={version} vagrant up --provider=virtualbox ``` + or on Windows, type: ``` - SET PREBUILT_VERSION={version} - vagrant up + SET PREBUILT_VERSION={version} + vagrant up --provider=virtualbox ``` + *The version must be only the numbers, not including the `v` in front, for example `24.05.00.2405260215` not `v24.05.00.2405260215`* *This process will take 10 minutes to maybe half an hour depending on your internet connection speed.* + ***Note:** The vagrant up command provisions the virtual machine on the first run. + For subsequent runs, you do not need to append the `--provider` flag as the VM is + already created.* + + + * **Build (from scratch) using QEMU on an M-Series Arm MacOKS** + + If you have an M-series ARM MacOS, run: + ``` + vagrant up --provider=qemu + ``` + + *As noted above, you do not need to append the `--provider` flag is only necessary on the first run when the VM is created.* + + * **Build from scratch** - If you wish to run `vagrant up` from scratch, on Linux or Mac type: + If you wish to run `vagrant up` from scratch, on Linux or IntelMac type: ``` FROM_SCRATCH=1 vagrant up ``` @@ -344,7 +364,7 @@ instructions. ``` -5. AND YOU ARE DONE! +7. AND YOU ARE DONE! When the installation has completed, you should see the message: ``` From ce0658a89ab4a792bb65066e2527e9c870624e12 Mon Sep 17 00:00:00 2001 From: Barb Cutler Date: Tue, 6 Aug 2024 15:02:21 -0400 Subject: [PATCH 05/13] Update vm_install_using_vagrant.md --- .../getting_started/vm_install_using_vagrant.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/_docs/developer/getting_started/vm_install_using_vagrant.md b/_docs/developer/getting_started/vm_install_using_vagrant.md index d94e945c..3789f049 100644 --- a/_docs/developer/getting_started/vm_install_using_vagrant.md +++ b/_docs/developer/getting_started/vm_install_using_vagrant.md @@ -180,10 +180,6 @@ and Intel machines and QEMU for M-Series ARM MacOS machines.* sudo dnf install vagrant ``` -DELETE - * **Note:** - When running vagrant up, use `vagrant up --provider=virtualbox` so it doesn't default to libvirt - * **Common errors when running vagrant up (Fedora/RHEL)** 1. Missing virtnetworkd: @@ -276,7 +272,9 @@ DELETE depending on your internet connection speed.* - ***Note:** The vagrant up command provisions the virtual machine on the first run. + ***Note:** The vagrant up command creates and provisions the virtual machine on the first run. + The `--provider` flag is important if you have more than one virtual box provider + installed on your machine (e.g., VirtualBox, VMWare, QEMU, libvirt). For subsequent runs, you do not need to append the `--provider` flag as the VM is already created.* @@ -288,7 +286,7 @@ DELETE vagrant up --provider=qemu ``` - *As noted above, you do not need to append the `--provider` flag is only necessary on the first run when the VM is created.* + *As noted above, the `--provider` flag is only necessary on the first run when the VM is created.* * **Build from scratch** From 822211dd818a55bd745b10fdf30969e2f1f5bb92 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A1tvik=20Karanam?= <89281036+skara9@users.noreply.github.com> Date: Tue, 6 Aug 2024 15:08:34 -0400 Subject: [PATCH 06/13] small corrections --- .../vm_install_using_vagrant.md | 21 +++++++++---------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/_docs/developer/getting_started/vm_install_using_vagrant.md b/_docs/developer/getting_started/vm_install_using_vagrant.md index 3789f049..7aa6be5a 100644 --- a/_docs/developer/getting_started/vm_install_using_vagrant.md +++ b/_docs/developer/getting_started/vm_install_using_vagrant.md @@ -14,8 +14,7 @@ Unix/Linux). The installation process will create a new Virtual Machine (VM) on your computer and the VM will use the Ubuntu GNU/Linux operating system. -***NOTE:** We only officially support and test development using VirtualBox for AMD -and Intel machines and QEMU for M-Series ARM MacOS machines.* +***NOTE:** We only officially support and test development using VirtualBox for AMD and Intel machines and QEMU for M-Series ARM MacOS machines.* --- @@ -52,12 +51,12 @@ and Intel machines and QEMU for M-Series ARM MacOS machines.* 5. If you're on M-series ARM MacOS (e.g., M1, M2, M3), you will be using QEMU with SMB file sharing. To enable this, open **System Settings** and navigate to **General > Sharing**. - Press the (i) button next to **File Sharing**, and in the popup window - click "Options...". Then turn on "Share files and folders using SMB" and + Press the (i) button next to **File Sharing**, and in thse popup window + click "Options...". Then turn on "Share files and folder using SMB" and check the box next to your name in the list below. 6. The complete installation process could take an hour or more and - will quite possiby fail if paused or interrupted. Make + will quite possibly fail if paused or interrupted. Make sure your internet connection is strong and consistent. You'll probably want to plug in your laptop power cord. Check your computer settings and make sure the machine does not hibernate or @@ -255,7 +254,7 @@ and Intel machines and QEMU for M-Series ARM MacOS machines.* vagrant up --provider=virtualbox ``` - If you wish to use a specific version of the pre-packaged Submitty VM, on Linux type: + If you wish to use a specific version of the pre-packaged Submitty VM, on Linux/MacOS type: ``` PREBUILT_VERSION={version} vagrant up --provider=virtualbox ``` @@ -273,25 +272,25 @@ and Intel machines and QEMU for M-Series ARM MacOS machines.* ***Note:** The vagrant up command creates and provisions the virtual machine on the first run. - The `--provider` flag is important if you have more than one virtual box provider + The `--provider` flag is important if you have more than one provider installed on your machine (e.g., VirtualBox, VMWare, QEMU, libvirt). For subsequent runs, you do not need to append the `--provider` flag as the VM is already created.* - * **Build (from scratch) using QEMU on an M-Series Arm MacOKS** + * **Build (from scratch) using QEMU on an M-Series Arm MacOS** - If you have an M-series ARM MacOS, run: + If you have an M-series ARM Mac, run: ``` vagrant up --provider=qemu ``` - *As noted above, the `--provider` flag is only necessary on the first run when the VM is created.* + *As noted above, you do not need to append the `--provider` flag on subsequent runs after the VM is already created.* * **Build from scratch** - If you wish to run `vagrant up` from scratch, on Linux or IntelMac type: + If you wish to run `vagrant up` from scratch, on Linux or Intel-based Mac type: ``` FROM_SCRATCH=1 vagrant up ``` From 2b89d50b4d76dfe4ae2615be2f565d7b6150910a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A1tvik=20Karanam?= <89281036+skara9@users.noreply.github.com> Date: Tue, 6 Aug 2024 15:08:45 -0400 Subject: [PATCH 07/13] update sidebar --- navtreedata.js | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/navtreedata.js b/navtreedata.js index 00cf62f1..10542796 100644 --- a/navtreedata.js +++ b/navtreedata.js @@ -195,9 +195,7 @@ var NAVTREE = [ "Review a Pull Request", "/developer/getting_started/review_a_pull_request", null ], [ "Commit to PR from Fork", "/developer/getting_started/commit_to_PR_from_fork", null ], [ "Edit Submitty Documentation", "/developer/getting_started/edit_submitty_documentation", null ], - [ "VM Install using Vagrant", "/developer/getting_started/vm_install_using_vagrant", [ - [ "Vagrant QEMU on Apple Silicon", "/developer/getting_started/vm_install_using_vagrant_apple_silicon", null ] - ] ], + [ "VM Install using Vagrant", "/developer/getting_started/vm_install_using_vagrant", null ], [ "Advanced Setup", "/developer/getting_started/phpstorm", [ [ "PhpStorm Setup Instructions", "/developer/getting_started/phpstorm", null ], [ "Xdebug Setup Instructions", "/developer/getting_started/xdebug", null ], From 7a391eb99cb4c6077bc9379074f08dd9f194c4a2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A1tvik=20Karanam?= <89281036+skara9@users.noreply.github.com> Date: Tue, 6 Aug 2024 15:15:11 -0400 Subject: [PATCH 08/13] more fixes --- .../vm_install_using_vagrant.md | 96 ++++++++++--------- 1 file changed, 49 insertions(+), 47 deletions(-) diff --git a/_docs/developer/getting_started/vm_install_using_vagrant.md b/_docs/developer/getting_started/vm_install_using_vagrant.md index 7aa6be5a..3dd12210 100644 --- a/_docs/developer/getting_started/vm_install_using_vagrant.md +++ b/_docs/developer/getting_started/vm_install_using_vagrant.md @@ -239,68 +239,70 @@ operating system. * **Build pre-packaged VM** - *NOTE: The pre-packaged Submitty VM is not (yet) - available for qemu / M-Series ARM Mac machines.* - - 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. This is a recently built machine, - but it may be slightly older than the current - [main branch on GitHub](https://github.com/Submitty/Submitty). - - - To create the virtual machine from the pre-packaged image, run: - ``` - vagrant up --provider=virtualbox - ``` - - If you wish to use a specific version of the pre-packaged Submitty VM, on Linux/MacOS type: - ``` - PREBUILT_VERSION={version} vagrant up --provider=virtualbox - ``` - - or on Windows, type: - ``` - SET PREBUILT_VERSION={version} - vagrant up --provider=virtualbox - ``` - - *The version must be only the numbers, not including the `v` in front, for example `24.05.00.2405260215` not `v24.05.00.2405260215`* - - *This process will take 10 minutes to maybe half an hour - depending on your internet connection speed.* - - - ***Note:** The vagrant up command creates and provisions the virtual machine on the first run. - The `--provider` flag is important if you have more than one provider - installed on your machine (e.g., VirtualBox, VMWare, QEMU, libvirt). - For subsequent runs, you do not need to append the `--provider` flag as the VM is - already created.* + *NOTE: The pre-packaged Submitty VM is not (yet) + available for qemu / M-Series ARM Mac machines.* + + 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. This is a recently built machine, + but it may be slightly older than the current + [main branch on GitHub](https://github.com/Submitty/Submitty). + + + To create the virtual machine from the pre-packaged image, run: + ``` + vagrant up --provider=virtualbox + ``` + + If you wish to use a specific version of the pre-packaged Submitty VM, on Linux/MacOS type: + ``` + PREBUILT_VERSION={version} vagrant up --provider=virtualbox + ``` + + or on Windows, type: + ``` + SET PREBUILT_VERSION={version} + vagrant up --provider=virtualbox + ``` + + *The version must be only the numbers, not including the `v` in front, for example `24.05.00.2405260215` not `v24.05.00.2405260215`* + + *This process will take 10 minutes to maybe half an hour + depending on your internet connection speed.* + + + ***Note:** The vagrant up command creates and provisions the virtual machine on the first run. + The `--provider` flag is important if you have more than one provider + installed on your machine (e.g., VirtualBox, VMWare, QEMU, libvirt). + For subsequent runs, you do not need to append the `--provider` flag as the VM is + already created.* * **Build (from scratch) using QEMU on an M-Series Arm MacOS** - If you have an M-series ARM Mac, run: - ``` - vagrant up --provider=qemu - ``` - - *As noted above, you do not need to append the `--provider` flag on subsequent runs after the VM is already created.* + If you have an M-series ARM Mac, run: + ``` + vagrant up --provider=qemu + ``` + + *As noted above, you do not need to append the `--provider` flag on subsequent runs after the VM is already created.* * **Build from scratch** If you wish to run `vagrant up` from scratch, on Linux or Intel-based Mac type: ``` - FROM_SCRATCH=1 vagrant up + FROM_SCRATCH=1 vagrant up --virtualbox ``` Or on Windows, type: ``` SET FROM_SCRATCH=1 - vagrant up + vagrant up --virtualbox ``` + *As noted above, you do not need to append the `--provider` flag on subsequent runs after the VM is already created.* + *This process will take anywhere from 30 minutes to a few hours depending on your internet speed.* @@ -325,13 +327,13 @@ operating system. * On Mac or Linux: ``` - NO_SUBMISSIONS=1 vagrant up + NO_SUBMISSIONS=1 vagrant up --provider=... ``` * Or on Windows using `cmd`: ``` SET NO_SUBMISSIONS=1 - vagrant up + vagrant up --provider=... ``` Or on Windows using PowerShell, you will have to set the environment variable differently: From cc47c6f13b55367d70f3a505c94163bf1091c1de Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A1tvik=20Karanam?= <89281036+skara9@users.noreply.github.com> Date: Tue, 6 Aug 2024 15:23:12 -0400 Subject: [PATCH 09/13] clarify no submissions only works from scratch --- .../vm_install_using_vagrant.md | 26 +++++++++++++------ 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/_docs/developer/getting_started/vm_install_using_vagrant.md b/_docs/developer/getting_started/vm_install_using_vagrant.md index 3dd12210..e4fedfab 100644 --- a/_docs/developer/getting_started/vm_install_using_vagrant.md +++ b/_docs/developer/getting_started/vm_install_using_vagrant.md @@ -316,7 +316,7 @@ operating system. users in the sample courses.* - * **Build without sample submissions** + * **Build from scratch without sample submissions** If your development work *will not require sample assignment submissions or autograding results*, you may prepend @@ -324,42 +324,52 @@ operating system. creation of these sample submissions and their autograding and decrease the time to complete installation. + * On Linux or Intel-based Mac: + ``` + NO_SUBMISSIONS=1 FROM_SCRATCH=1 vagrant up --provider=virtualbox + ``` - * On Mac or Linux: + * On M-series ARM Mac: ``` - NO_SUBMISSIONS=1 vagrant up --provider=... + NO_SUBMISSIONS=1 vagrant up --provider=qemu ``` - * Or on Windows using `cmd`: + * On Windows using `cmd`: ``` SET NO_SUBMISSIONS=1 - vagrant up --provider=... + SET FROM_SCRATCH=1 + vagrant up --provider=virtualbox ``` - Or on Windows using PowerShell, you will have to set the environment variable differently: + On Windows using PowerShell, you will have to set the environment variables differently: ```pwsh $Env:NO_SUBMISSIONS=1 + $Env:FROM_SCRATCH=1 vagrant up ``` - If you want to unset the variable later in `cmd`, you can do: + If you want to unset the variables later in `cmd`, you can do: ``` SET NO_SUBMISSIONS= + SET FROM_SCRATCH= ``` Or in PowerShell: ```pwsh Remove-Item Env:\NO_SUBMISSIONS + Remove-Item Env:\FROM_SCRATCH ``` - Similarly, you can check that the variable is set by doing: + Similarly, you can check that the variables are set in `cmd` with: ``` SET NO_SUBMISSIONS + SET FROM_SCRATCH ``` Or in PowerShell: ```pwsh $Env:NO_SUBMISSIONS + $Env:FROM_SCRATCH ``` From 929d9f59c6474b55edafd4d48a61e0c8e8cd441f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A1tvik=20Karanam?= <89281036+skara9@users.noreply.github.com> Date: Tue, 6 Aug 2024 15:23:59 -0400 Subject: [PATCH 10/13] small fix --- _docs/developer/getting_started/vm_install_using_vagrant.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/developer/getting_started/vm_install_using_vagrant.md b/_docs/developer/getting_started/vm_install_using_vagrant.md index e4fedfab..36856149 100644 --- a/_docs/developer/getting_started/vm_install_using_vagrant.md +++ b/_docs/developer/getting_started/vm_install_using_vagrant.md @@ -295,7 +295,7 @@ operating system. FROM_SCRATCH=1 vagrant up --virtualbox ``` - Or on Windows, type: + Or on Windows with `cmd`, type: ``` SET FROM_SCRATCH=1 vagrant up --virtualbox From f9820292d7cf355a005d2fe63db3990d0d9b5d3f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A1tvik=20Karanam?= <89281036+skara9@users.noreply.github.com> Date: Tue, 6 Aug 2024 15:27:29 -0400 Subject: [PATCH 11/13] small fix --- _docs/developer/getting_started/vm_install_using_vagrant.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_docs/developer/getting_started/vm_install_using_vagrant.md b/_docs/developer/getting_started/vm_install_using_vagrant.md index 36856149..ca903f3c 100644 --- a/_docs/developer/getting_started/vm_install_using_vagrant.md +++ b/_docs/developer/getting_started/vm_install_using_vagrant.md @@ -51,8 +51,8 @@ operating system. 5. If you're on M-series ARM MacOS (e.g., M1, M2, M3), you will be using QEMU with SMB file sharing. To enable this, open **System Settings** and navigate to **General > Sharing**. - Press the (i) button next to **File Sharing**, and in thse popup window - click "Options...". Then turn on "Share files and folder using SMB" and + Press the (i) button next to **File Sharing**, and in the popup window + click "Options...". Then turn on "Share files and folders using SMB" and check the box next to your name in the list below. 6. The complete installation process could take an hour or more and From fd33293dcd4c85f039469af06ca47b5c4883ada7 Mon Sep 17 00:00:00 2001 From: Barb Cutler Date: Wed, 7 Aug 2024 11:32:13 -0400 Subject: [PATCH 12/13] update navtree --- navtreedata.js | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/navtreedata.js b/navtreedata.js index 00cf62f1..10542796 100644 --- a/navtreedata.js +++ b/navtreedata.js @@ -195,9 +195,7 @@ var NAVTREE = [ "Review a Pull Request", "/developer/getting_started/review_a_pull_request", null ], [ "Commit to PR from Fork", "/developer/getting_started/commit_to_PR_from_fork", null ], [ "Edit Submitty Documentation", "/developer/getting_started/edit_submitty_documentation", null ], - [ "VM Install using Vagrant", "/developer/getting_started/vm_install_using_vagrant", [ - [ "Vagrant QEMU on Apple Silicon", "/developer/getting_started/vm_install_using_vagrant_apple_silicon", null ] - ] ], + [ "VM Install using Vagrant", "/developer/getting_started/vm_install_using_vagrant", null ], [ "Advanced Setup", "/developer/getting_started/phpstorm", [ [ "PhpStorm Setup Instructions", "/developer/getting_started/phpstorm", null ], [ "Xdebug Setup Instructions", "/developer/getting_started/xdebug", null ], From 507eb23cb48d470656128d0e7d514e03183495d5 Mon Sep 17 00:00:00 2001 From: Barb Cutler Date: Thu, 8 Aug 2024 12:05:25 -0400 Subject: [PATCH 13/13] tweaks --- .../vm_install_using_vagrant.md | 85 ++++++++++--------- 1 file changed, 43 insertions(+), 42 deletions(-) diff --git a/_docs/developer/getting_started/vm_install_using_vagrant.md b/_docs/developer/getting_started/vm_install_using_vagrant.md index ca903f3c..3b816082 100644 --- a/_docs/developer/getting_started/vm_install_using_vagrant.md +++ b/_docs/developer/getting_started/vm_install_using_vagrant.md @@ -14,7 +14,9 @@ Unix/Linux). The installation process will create a new Virtual Machine (VM) on your computer and the VM will use the Ubuntu GNU/Linux operating system. -***NOTE:** We only officially support and test development using VirtualBox for AMD and Intel machines and QEMU for M-Series ARM MacOS machines.* +***NOTE:** We only officially support and test development using +VirtualBox for AMD and Intel machines and QEMU for +M-Series ARM MacOS machines.* --- @@ -47,16 +49,17 @@ operating system. ***NOTE:** Installing WSL2 may also reconfigure your OS to use Hyper-V or Windows hypervisor platform and prevent VirtualBox from working correctly. It is recommended to not install - or use WSL2 alongside Virtualbox for now.* + or use WSL2 alongside VirtualBox for now.* -5. If you're on M-series ARM MacOS (e.g., M1, M2, M3), you will be using QEMU with SMB file sharing. +5. If you're on an M-series ARM MacOS (e.g., M1, M2, M3), + you will be using QEMU with SMB file sharing. To enable this, open **System Settings** and navigate to **General > Sharing**. Press the (i) button next to **File Sharing**, and in the popup window click "Options...". Then turn on "Share files and folders using SMB" and check the box next to your name in the list below. 6. The complete installation process could take an hour or more and - will quite possibly fail if paused or interrupted. Make + will probably fail if paused or interrupted. Make sure your internet connection is strong and consistent. You'll probably want to plug in your laptop power cord. Check your computer settings and make sure the machine does not hibernate or @@ -86,8 +89,9 @@ operating system. 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. + [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. @@ -112,15 +116,14 @@ operating system. to self-sign the necessary packages to run Vagrant and VirtualBox. 2. DOWNLOAD AND INSTALL THE LATEST DEPENDENCIES + *Follow the instructions below specific to your host operating system* - * You will need: - *Follow the instructions below specific to your host operating system* - + * You will need: * [Ruby](https://www.ruby-lang.org/en/downloads) * [Git](https://git-scm.com/downloads) - * M-SERIES ARM MacOS: [QEMU](https://www.qemu.org) - * EVERYONE ELSE: [VirtualBox](https://www.virtualbox.org/wiki/Download_Old_Builds_6_1) * [Vagrant](https://www.vagrantup.com) + * *M-SERIES ARM MacOS:* [QEMU](https://www.qemu.org) + * *EVERYONE ELSE:* [VirtualBox](https://www.virtualbox.org/wiki/Download_Old_Builds_6_1) * **MacOS** @@ -162,14 +165,14 @@ operating system. * 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 + 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: + and then inputting your password when prompted. + Then install the Virtual Box rpm using: ``` sudo dnf install VirtualBox-xxxxx.rpm ``` @@ -205,7 +208,8 @@ operating system. ***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.* + the repo and use the git url from your fork instead, especially if you are looking to + contribute. You will then make PRs to the main Submitty repository from branches on your fork.* * **OPTIONAL:** If you will be developing code in one of the companion @@ -240,7 +244,7 @@ operating system. * **Build pre-packaged VM** *NOTE: The pre-packaged Submitty VM is not (yet) - available for qemu / M-Series ARM Mac machines.* + available for QEMU / M-Series ARM Mac machines.* If you are using VirtualBox as your provider, you will by default use a pre-packaged Submitty VM. This will have all of Submitty @@ -274,36 +278,33 @@ operating system. ***Note:** The vagrant up command creates and provisions the virtual machine on the first run. The `--provider` flag is important if you have more than one provider installed on your machine (e.g., VirtualBox, VMWare, QEMU, libvirt). - For subsequent runs, you do not need to append the `--provider` flag as the VM is + For subsequent runs of `vagrant up` (e.g., to re-start the VM), + you do not need to append the `--provider` flag as the VM is already created.* - * **Build (from scratch) using QEMU on an M-Series Arm MacOS** - - If you have an M-series ARM Mac, run: - ``` - vagrant up --provider=qemu - ``` - - *As noted above, you do not need to append the `--provider` flag on subsequent runs after the VM is already created.* - - * **Build from scratch** - If you wish to run `vagrant up` from scratch, on Linux or Intel-based Mac type: - ``` - FROM_SCRATCH=1 vagrant up --virtualbox - ``` + * Using QEMU on an M-Series Arm MacOS, type: + ``` + vagrant up --provider=qemu + ``` + + * On Linux or Intel-based Mac, type: + ``` + FROM_SCRATCH=1 vagrant up --provider=virtualbox + ``` - Or on Windows with `cmd`, type: - ``` - SET FROM_SCRATCH=1 - vagrant up --virtualbox - ``` + * Or on Windows with `cmd`, type: + ``` + SET FROM_SCRATCH=1 + vagrant up --provider=virtualbox + ``` - *As noted above, you do not need to append the `--provider` flag on subsequent runs after the VM is already created.* + *As noted above, you do not need to append the `--provider` flag on + subsequent runs of `vagrant up` after the VM is already created.* - *This process will take anywhere from 30 minutes to a few hours + *Building the VM from scratch will take anywhere from 30 minutes to a few hours depending on your internet speed.* @@ -324,14 +325,14 @@ operating system. creation of these sample submissions and their autograding and decrease the time to complete installation. - * On Linux or Intel-based Mac: + * On M-series ARM Mac: ``` - NO_SUBMISSIONS=1 FROM_SCRATCH=1 vagrant up --provider=virtualbox + NO_SUBMISSIONS=1 vagrant up --provider=qemu ``` - * On M-series ARM Mac: + * On Linux or Intel-based Mac: ``` - NO_SUBMISSIONS=1 vagrant up --provider=qemu + NO_SUBMISSIONS=1 FROM_SCRATCH=1 vagrant up --provider=virtualbox ``` * On Windows using `cmd`: