Skip to content

[Documentation:Developer] Virtualbox is only supported provider #714

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

[Documentation:Developer] Virtualbox is only supported provider #714

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions Gemfile.lock
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ GEM
logger
faraday-net_http (3.1.1)
net-http
ffi (1.17.2-aarch64-linux-gnu)
ffi (1.17.2-arm64-darwin)
ffi (1.17.2-x64-mingw-ucrt)
ffi (1.17.2-x86_64-linux-gnu)
Expand Down Expand Up @@ -239,6 +240,8 @@ GEM
mutex_m (0.2.0)
net-http (0.4.1)
uri
nokogiri (1.18.9-aarch64-linux-gnu)
racc (~> 1.4)
nokogiri (1.18.9-arm64-darwin)
racc (~> 1.4)
nokogiri (1.18.9-x64-mingw-ucrt)
Expand Down Expand Up @@ -284,6 +287,7 @@ GEM
yell (2.2.2)

PLATFORMS
aarch64-linux-gnu
arm64-darwin-22
arm64-darwin-23
arm64-darwin-24
Expand Down
41 changes: 5 additions & 36 deletions _docs/developer/getting_started/vm_install_using_vagrant.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,7 @@ 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.*
VirtualBox.*

---

Expand Down Expand Up @@ -51,14 +50,7 @@ M-Series ARM MacOS machines.*
platform and prevent VirtualBox from working correctly. It is recommended to not install
or use WSL2 alongside VirtualBox for now.*

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
5. The complete installation process could take an hour or more and
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
Expand Down Expand Up @@ -122,24 +114,14 @@ M-Series ARM MacOS machines.*
* [Ruby](https://www.ruby-lang.org/en/downloads)
* [Git](https://git-scm.com/downloads)
* [Vagrant](https://developer.hashicorp.com/vagrant/install)
* *M-SERIES ARM MacOS:* [QEMU](https://www.qemu.org)
* *EVERYONE ELSE:* [VirtualBox](https://www.virtualbox.org/wiki/Downloads)
* [VirtualBox](https://www.virtualbox.org/wiki/Downloads)
* Ensure VirtualBox version is compatible with Vagrant.


* **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:

If you have an M-series ARM Mac, run:
```
brew install --cask vagrant
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
Expand Down Expand Up @@ -243,9 +225,6 @@ M-Series ARM MacOS machines.*


* **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
Expand Down Expand Up @@ -285,13 +264,8 @@ M-Series ARM MacOS machines.*


* **Build from scratch**

* Using QEMU on an M-Series Arm MacOS, type:
```
vagrant up --provider=qemu
```

* On Linux or Intel-based Mac, type:
* On Linux or Mac, type:
```
FROM_SCRATCH=1 vagrant up --provider=virtualbox
```
Expand Down Expand Up @@ -326,12 +300,7 @@ M-Series ARM MacOS machines.*
creation of these sample submissions and their autograding and
decrease the time to complete installation.

* On M-series ARM Mac:
```
NO_SUBMISSIONS=1 vagrant up --provider=qemu
```

* On Linux or Intel-based Mac:
* On Linux or Mac:
```
NO_SUBMISSIONS=1 FROM_SCRATCH=1 vagrant up --provider=virtualbox
```
Expand Down
26 changes: 4 additions & 22 deletions _docs/developer/getting_started/worker_vm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,22 +31,7 @@ machines* in addition to your primary vagrant virtual machine.

_NOTE: This will create the vagrant configuration file: `.vagrant/workers.json`._


4. If you are on MacOS running QEMU, restart the network socket in public mode:
```
vagrant workers socket restart --public
```
_NOTE: Using the `--public` flag will make your worker VMs accessible to anyone
on your local network, which may be a modest security concern.
We suggest this to minimize possibility of errors while creating the
worker machines and will revert this in a later step._

_NOTE: Running a socket command while a worker machine is running can detach the
process, making the VM inaccessible to vagrant. If this happens and you are unable
to `vagrant workers halt`, then you may run `pkill -15 -f qemu-system-` to kill
all virtual machines running on your computer (including the main Submitty VM)._

6. Now you can create the worker machine(s) with:
4. Now you can create the worker machine(s) with:
```
vagrant workers up
```
Expand All @@ -55,26 +40,23 @@ machines* in addition to your primary vagrant virtual machine.

When this is finished, you should see the Submitty duck ASCII art for each new worker machine.

7. You can verify that all the worker machines are running with:
5. You can verify that all the worker machines are running with:
```
vagrant workers status
```

8. `vagrant ssh` into the main virtual machine and run:
6. `vagrant ssh` into the main virtual machine and run:
```
refresh_vagrant_workers # (runs python3 /usr/local/submitty/GIT_CHECKOUT/Submitty/.setup/bin/refresh_vagrant_workers.py)
submitty_install
```

9. To stop the worker machines, you can run:
7. To stop the worker machines, you can run:
```
vagrant workers halt
vagrant workers socket stop
```

_For MacOS QEMU users: Once the virtual machine(s) are halted, if you would like to restart under
private networking, you may do so by omitting the `--public` flag from the `vagrant workers socket start` command._


---

Expand Down
23 changes: 7 additions & 16 deletions _docs/developer/troubleshooting/installation_troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -190,7 +190,7 @@ References and useful links: [https://gist.github.com/pjdietz/5768124](https://g

## SSH connection was unexpectedly closed

* If you see an error similar to on ARM64 Machine (Apple Silicon):
* If you see an error similar to:

```
The SSH connection was unexpectedly closed by the remote end. This
Expand Down Expand Up @@ -219,19 +219,10 @@ References and useful links: [https://gist.github.com/pjdietz/5768124](https://g
vagrant box update
```

* Verify qemu is install correctly

* Firstly, use this command will display the installed version of QEMU for ARM64.
```
qemu-system-aarch64 --version
```

* Secondly, Verify that the QEMU binary for ARM64 is accessible in your system's PATH by running:
```
which qemu-system-aarch64
```

*Note: This command will display the path to the QEMU ARM64 binary (e.g., /opt/homebrew/bin/qemu-system-aarch64)
* Verify Virtualbox is install correctly
```
VirtualBox -h
```

* Verify Vagrant Installation
```
Expand Down Expand Up @@ -262,9 +253,9 @@ References and useful links: [https://gist.github.com/pjdietz/5768124](https://g
vagrant destroy
```

* Boots up a new Vagrant environment using the QEMU provider
* Boots up a new Vagrant environment
```
vagrant up --provider=qemu
vagrant up --provider=virtualbox
```

---
Expand Down
Loading