Skip to content

Commit f0f1ec3

Browse files
authored
Update vm_install_using_vagrant.md
1 parent 48f0427 commit f0f1ec3

File tree

1 file changed

+66
-46
lines changed

1 file changed

+66
-46
lines changed

_docs/developer/getting_started/vm_install_using_vagrant.md

Lines changed: 66 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,8 @@ Unix/Linux). The installation process will create a new Virtual
1414
Machine (VM) on your computer and the VM will use the Ubuntu GNU/Linux
1515
operating system.
1616

17-
__Note:__ We only officially support and test development using VirtualBox.
18-
The instructions below are for VirtualBox. While alternatively using
19-
VMWare should work, we have not tested this, and do not provide these
20-
instructions.
17+
***NOTE:** We only officially support and test development using VirtualBox for AMD
18+
and Intel machines and QEMU for M-Series ARM MacOS machines.*
2119

2220
---
2321

@@ -43,24 +41,23 @@ instructions.
4341
backend, which will be slower and can cause instability in the
4442
VM.
4543

46-
**Note:**
47-
This may stop programs like Docker Desktop and WSL 2 from
44+
***NOTE:** This may stop programs like Docker Desktop and WSL 2 from
4845
working. If these programs are essential to your workflow, consider
4946
looking up how to add a separate boot entry with "hypervisorlaunchtype"
50-
set to "off" for use with VirtualBox.
47+
set to "off" for use with VirtualBox.*
5148

52-
**Note:**
53-
Installing WSL2 may also reconfigure your OS to use Hyper-V or Windows hypervisor
49+
***NOTE:** Installing WSL2 may also reconfigure your OS to use Hyper-V or Windows hypervisor
5450
platform and prevent VirtualBox from working correctly. It is recommended to not install
55-
or use WSL2 alongside Virtualbox for now.
51+
or use WSL2 alongside Virtualbox for now.*
5652

57-
5. If you're on M-series macOS, you will be using QEMU with SMB file sharing.
53+
5. If you're on M-series ARM MacOS (e.g., M1, M2, M3), you will be using QEMU with SMB file sharing.
5854
To enable this, open **System Settings** and navigate to **General > Sharing**.
5955
Press the (i) button next to **File Sharing**, and in the popup window
6056
click "Options...". Then turn on "Share files and folders using SMB" and
6157
check the box next to your name in the list below.
6258

63-
6. The complete installation process could take an hour or more. Make
59+
6. The complete installation process could take an hour or more and
60+
will quite possiby fail if paused or interrupted. Make
6461
sure your internet connection is strong and consistent. You'll
6562
probably want to plug in your laptop power cord. Check your
6663
computer settings and make sure the machine does not hibernate or
@@ -110,7 +107,7 @@ instructions.
110107
3. Locate **Virtualization** and enable it. (Some motherboards may call it SVM, AMD-V, VT-x/Vanderpool)
111108
4. Be sure to choose **Hardware Virtualization** in the **System -> Acceleration**
112109
settings of the virtual machine you are using.
113-
5. **Note:** If using secure boot, Vagrant may fail to work with VirtualBox.
110+
5. **NOTE:** If using secure boot, Vagrant may fail to work with VirtualBox.
114111
You will then either need to disable secure boot from the boot menu/BIOS or
115112
follow [these steps](https://era86.github.io/2018/01/24/vagrant-virtualbox-secureboot-in-ubuntu-1604.html)
116113
to self-sign the necessary packages to run Vagrant and VirtualBox.
@@ -122,18 +119,27 @@ instructions.
122119

123120
* [Ruby](https://www.ruby-lang.org/en/downloads)
124121
* [Git](https://git-scm.com/downloads)
125-
* [VirtualBox](https://www.virtualbox.org/wiki/Download_Old_Builds_6_1) (or [QEMU](https://www.qemu.org) instead for M-series macOS)
122+
* M-SERIES ARM MacOS: [QEMU](https://www.qemu.org)
123+
* EVERYONE ELSE: [VirtualBox](https://www.virtualbox.org/wiki/Download_Old_Builds_6_1)
126124
* [Vagrant](https://www.vagrantup.com)
127125

128126

129127
* **MacOS**
130128
You can either go to respective sites and download the necessary binaries or
131-
install [Homebrew](http://brew.sh/), if you don't have it, and then run:
129+
install [Homebrew](http://brew.sh/), if you don't have it, and then:
132130

131+
If you have an M-series ARM Mac, run:
133132
```
134133
brew install --cask vagrant
135-
brew install --cask virtualbox # if on Intel chip
136-
brew install qemu && vagrant plugin install vagrant-qemu # if on M-series chip
134+
brew install qemu
135+
vagrant plugin install vagrant-qemu
136+
```
137+
138+
Or if you have an older Intel-based Mac, run:
139+
140+
```
141+
brew install --cask vagrant
142+
brew install --cask virtualbox
137143
```
138144
139145
* **Windows**
@@ -174,6 +180,7 @@ instructions.
174180
sudo dnf install vagrant
175181
```
176182
183+
DELETE
177184
* **Note:**
178185
When running vagrant up, use `vagrant up --provider=virtualbox` so it doesn't default to libvirt
179186
@@ -193,22 +200,23 @@ instructions.
193200
run `vagrant destroy` before re-running `vagrant up --provider=virtualbox` again.
194201
195202
196-
3. CLONE THE [SUBMITTY REPOSITORY](https://github.com/Submitty/Submitty)
203+
4. CLONE THE [SUBMITTY REPOSITORY](https://github.com/Submitty/Submitty)
197204
198205
* Clone it to a location on your computer (the "host").
199206
200207
```
201208
git clone https://github.com/Submitty/Submitty.git
202209
```
203210
204-
**Note:** If you are not currently part of the Submitty organization on GitHub, you may want to
211+
***NOTE:** If you are not currently part of the Submitty organization on GitHub, you may want to
205212
[fork](https://help.github.com/en/github/getting-started-with-github/fork-a-repo)
206-
the repo and use the git url from your fork instead, especially if you are looking to contribute.
213+
the repo and use the git url from your fork instead, especially if you are looking to contribute.*
214+
207215
208-
* _OPTIONAL: If you will be developing code in one of the companion
216+
* **OPTIONAL:** If you will be developing code in one of the companion
209217
Submitty repositories (e.g., AnalysisTools, Lichen,
210218
Localization, RainbowGrades, Tutorial), also clone those
211-
repositories to the same directory. For example:_
219+
repositories to the same directory. For example:
212220
213221
```
214222
home
@@ -223,57 +231,69 @@ instructions.
223231
└── Tutorial (optional)
224232
```
225233
226-
_This host directory structure will be shared / synced between
227-
your host operating system and the Submitty virtual machine._
234+
*This host directory structure will be shared / synced between
235+
your host operating system and the Submitty virtual machine.*
228236
229237
230-
4. RUN VAGRANT
231-
232-
If you have an AMD processor you can choose to download a pre-made
233-
VM that is created weekly OR you can create the VM from scratch
234-
(which will take substantially more time). If you have an ARM chip
235-
(such as Apple M-series), you must create the VM from
236-
scratch.
238+
5. RUN VAGRANT
237239
238240
239241
* Navigate into the Submitty repository on your computer in a
240-
shell/terminal. _On Windows, run CMD or PowerShell on administrator mode_.
242+
shell/terminal. *On Windows, run CMD or PowerShell on administrator mode.*
241243
242244
243245
* **Build pre-packaged VM**
244246
247+
*NOTE: The pre-packaged Submitty VM is not (yet)
248+
available for qemu / M-Series ARM Mac machines.*
249+
245250
If you are using VirtualBox as your provider, you will by default
246-
use a pre-packaged Submitty VM. This will have all of Submitty
247-
already setup. Vagrant will build your VM for you.
251+
use a pre-packaged Submitty VM. This will have all of Submitty
252+
already setup. This is a recently built machine,
253+
but it may be slightly older than the current
254+
[main branch on GitHub](https://github.com/Submitty/Submitty).
255+
248256
249-
To create the virtual machine, run:
257+
To create the virtual machine from the pre-packaged image, run:
250258
```
251259
vagrant up --provider=virtualbox
252260
```
253-
Replace `virtualbox` with `qemu` if on M-series macOS.
254-
255-
***Note:** The vagrant up command provisions the virtual machine on the first run.
256-
For subsequent runs, you do not need to append the `--provider` flag as the VM is
257-
already created.*
258261
259-
If you wish to use a specific version of the pre-packaged Submitty VM, on Linux or Mac type:
262+
If you wish to use a specific version of the pre-packaged Submitty VM, on Linux type:
260263
```
261-
PREBUILT_VERSION={version} vagrant up
264+
PREBUILT_VERSION={version} vagrant up --provider=virtualbox
262265
```
266+
263267
or on Windows, type:
264268
```
265-
SET PREBUILT_VERSION={version}
266-
vagrant up
269+
SET PREBUILT_VERSION={version}
270+
vagrant up --provider=virtualbox
267271
```
272+
268273
*The version must be only the numbers, not including the `v` in front, for example `24.05.00.2405260215` not `v24.05.00.2405260215`*
269274
270275
*This process will take 10 minutes to maybe half an hour
271276
depending on your internet connection speed.*
272277
273278
279+
***Note:** The vagrant up command provisions the virtual machine on the first run.
280+
For subsequent runs, you do not need to append the `--provider` flag as the VM is
281+
already created.*
282+
283+
284+
* **Build (from scratch) using QEMU on an M-Series Arm MacOKS**
285+
286+
If you have an M-series ARM MacOS, run:
287+
```
288+
vagrant up --provider=qemu
289+
```
290+
291+
*As noted above, you do not need to append the `--provider` flag is only necessary on the first run when the VM is created.*
292+
293+
274294
* **Build from scratch**
275295
276-
If you wish to run `vagrant up` from scratch, on Linux or Mac type:
296+
If you wish to run `vagrant up` from scratch, on Linux or IntelMac type:
277297
```
278298
FROM_SCRATCH=1 vagrant up
279299
```
@@ -344,7 +364,7 @@ instructions.
344364
```
345365
346366
347-
5. AND YOU ARE DONE!
367+
7. AND YOU ARE DONE!
348368
349369
When the installation has completed, you should see the message:
350370
```

0 commit comments

Comments
 (0)