Skip to content
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

[Documentation:Developer] Reorganize troubleshooting #565

Merged
merged 15 commits into from
Dec 12, 2023
Merged

[Documentation:Developer] Reorganize troubleshooting #565

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
2693637
Developer Troubleshooting Reorganized
RitaLei123 Nov 7, 2023
0160ff0
Remove Index Page
RitaLei123 Nov 7, 2023
c4c9ca5
Fixing Typo
RitaLei123 Nov 12, 2023
5a610dc
Updating Path for Re Creating Sample Course Data
RitaLei123 Nov 12, 2023
2e00a55
Merge branch 'main' into Reorganize-Troubleshooting
RitaLei123 Nov 12, 2023
de7a495
Fix Path
RitaLei123 Nov 12, 2023
a000a39
Merge branch 'Reorganize-Troubleshooting' of https://github.com/Submi…
RitaLei123 Nov 12, 2023
601fb9d
Fix PR
RitaLei123 Dec 12, 2023
a49fc87
Fix navtreedata.js
RitaLei123 Dec 12, 2023
7fa9534
Remove reinstallation_troubleshooting instances
RitaLei123 Dec 12, 2023
623cad3
fix gem file
RitaLei123 Dec 12, 2023
b98d252
Gemfile fix
RitaLei123 Dec 12, 2023
608d394
lockfile
RitaLei123 Dec 12, 2023
2a13d61
Ruby
RitaLei123 Dec 12, 2023
535b58c
minor edits
Dec 12, 2023
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
128 changes: 1 addition & 127 deletions _docs/developer/development_instructions/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ complicated and expensive steps at the bottom of the page._

Please also see [Installation Version Notes](/sysadmin/installation/version_notes)

Please also see [Re-Installation Troubleshooting](/developer/troubleshooting/reinstallation_troubleshooting)

---

Expand Down Expand Up @@ -204,133 +205,6 @@ autograding configuration, you'll probably need to:

---

## System Clock Testing & Troubleshooting
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i agree with moving the system clock troubleshooting to another file


* If the VM has a clock skew (incorrect time)

```
sudo service ntp stop
sudo ntpd -gq
sudo service ntp start
```


* If you need to test time and/or date dependent elements, you can
change it in the vagrant machine so you don't have to wait. To
remove the syncing and set your own time:

```
sudo systemctl disable ntp
timedatectl set-ntp 0
sudo date -s "<year>-<month>-<day> <hour>:<minute>:<seconds>
```

To check the date, helpful to make sure the date and time you set has stuck:

```
date
```

To sync back with the current time:

```
sudo systemctl enable ntp
timedatectl set-ntp 1
```

---

## System Re-Configuration
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

but the instructions for teting changes to configure_submitty.py & etc should stay here


If recent development changes include modifications to files affecting
the system installation process (e.g., changes to
`CONFIGURE_SUBMITTY.py`, `install_system.sh`, `Vagrantfile`), you will
need to either re-provision or re-build your VM from scratch to test
these changes.

* To re-run the initial configuration step of Submitty, use this command:

```
sudo python3 /usr/local/submitty/GIT_CHECKOUT/Submitty/.setup/CONFIGURE_SUBMITTY.py
```

* To update existing databases:

```
sudo python3 /usr/local/submitty/GIT_CHECKOUT/Submitty/.setup/update_database.py
```


---

## Re-Creating All Sample Course Data
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

and the instructions for rebuilding sample course data should stay here


* If you've changed the script to create a new course
(`create_course.sh`), or the schema for the master database
(`submitty_db.sql`), or the schema for the course databases
(`course_tables.sql`), or you changed student/gradeable data
we need to delete all courses and recreate
the course databases, users, and sample submission uploads.

_NOTE: Make sure you are not be connected to any DBs (e.g., through
pgAdmin) or else running the below scripts could put things into a
broken state._

Run this command:

```
sudo bash /usr/local/submitty/GIT_CHECKOUT/Submitty/.setup/bin/recreate_sample_courses.sh
```

You can append the `--no_submissions` flag to the above command to
skip creation of any sample submission data in the sample courses.
This will accelerate the completion of this command, but you will be
missing the hundreds of sample student submissions present in the
full installation.


NOTE: This command will also have to be run twice a year on July 1st and January 1st when the test semester will change from fall to spring or vice versa.


See also: [Sample Course Data](/developer/development_instructions/sample_data)

---

## Complete System Re-Installation
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

and system re-installation instructions should stay here


* To re-provision your VM, exit the VM, and from a terminal your host
machine within the Submitty GIT repository type:

```
vagrant reload --provision
```

Or if the VM is not already running:

```
vagrant up --provision
```

This is will be faster than doing a full `destroy`/`up`, however
depending on the changes you've done to the VM, could leave it
potentially unstable.

* Alternatively, re-build your VM from scratch:

```
vagrant destroy
vagrant up
```

_NOTE: This process will take a bit of time (45 minutes or more),
and requires an internet connection. It will delete any assignments
you've uploaded to your VM installation. And it will erase any
files you have created/edited within your VM that are not part of
the shared directory of the Submitty working repository. It will
also destroy the databases, and any grading configuration or grading
work that has been done._

---

## Virtual Machine Recovery using Snapshots

Expand Down
3 changes: 1 addition & 2 deletions _docs/developer/development_instructions/sample_data.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,5 +72,4 @@ You may also need to edit test cases in Cypress, Selenium, etc.

---

See also: [Re-Creating All Sample Course Data](/developer/development_instructions/index#re-creating-all-sample-course-data)

See also: [Re-Creating All Sample Course Data](/developer/troubleshooting/reinstallation_troubleshooting)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

so we will revert this change

102 changes: 0 additions & 102 deletions _docs/developer/development_instructions/troubleshooting.md
View file
Open in desktop

This file was deleted.

82 changes: 1 addition & 81 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 @@ -258,9 +258,7 @@ Below are quick steps to get everything installed and running.
If you do not see this message due to an error or the installation
has frozen, check out:

* [Installation Troubleshooting](#installation-troubleshooting)

* [Development Instructions Troubleshooting](/developer/development_instructions/troubleshooting)
* [Installation Troubleshooting](/developer/troubleshooting/installation_troubleshooting)

---

Expand Down Expand Up @@ -402,84 +400,6 @@ Below are quick steps to get everything installed and running.
```
vagrant up
```

---

## Installation Troubleshooting

* If your install becomes stuck on ``SSH auth method: private key`` for more than three minutes,
then what you can do is open Virtual Box, navigate to your VM, and click the green "Show" button.
Having the VM's terminal GUI open can seem to keep it awake for communication. While developing on Submitty,
this "Show" terminal option can sometimes lead to the VM being faster with loads, so it may be worth having the GUI
open even after your vagrant up.

* If your install seems to randomly freeze during `vagrant up`
with no explanation, then there are a couple of things that may be going wrong:

*Note: If this happens, it may be worth running a simple `vagrant destroy` before you try to `vagrant up` again. It is possible to repair, but it is usually more effort than it is worth.*

* First, check to make sure you have a solid internet connection.
Even if the connection is fast, it may experience drop-outs every
once in a while, so it is highly recommended to install it with a wired
connection to the internet.

* Secondly, check to make sure your computer is not going to
sleep, this can be changed in settings for some systems, or you
can install a program to keep it awake (for example, amphetamine on Mac).

* If an error is thrown during `vagrant up`, you may need to
uninstall Virtual Box and all virtual machines by typing the
following commands:

_CAUTION: This should only be done if you do not have any other virtual machines._

To remove Virtual Box type:

```
sudo apt-get remove --purge virtualbox
```
To remove all virtual machines and configuration files type:

```
sudo rm ~/"VirtualBox VMs" -Rf
sudo rm ~/.config/VirtualBox/ -Rf
```
This will delete all virtual machine settings. Then install
the latest version of Virtual Box and vagrant from the links given in step 3 (using Ubuntu Software).

* If it has been a while since your last `vagrant destroy` and
`vagrant up` you may need to update/upgrade/reinstall the virtual
box, vagrant, and the installed boxes on your
system:

For example, on Mac:

```
brew reinstall --cask virtualbox
brew reinstall --cask vagrant
vagrant plugin update
vagrant box update
```

If you continue to have errors on Mac with `vagrant up` after
reinstalling virtualbox and vagrant, check "System Preferences" ->
"Security & Privacy". You may need to approve/reapprove
"Allow apps download from". You may also need to restart your computer.

Similar instructions for other OS.

* If this error is thrown during `vagrant up` command:
```
ubuntu-26.84: E: Failed to fetch http://us.archive.ubuntu.com/ubuntu/pool/main/g/gcc-9gcc-9_9.4.0-1ubuntu1-20.84.1_amd64.deb Connection fail [IP: 189.211.241.193]
```
then you should use VPN to connect to the internet and then try `vagrant up`.This error usually occurs when you are outside the United States and the connection to the Ubuntu package repository is being blocked or restricted.

__Note:__ The IP address provided in the error message may vary.
ProtonVPN, which provides free VPN service can be used. You can download from their official website at (https://protonvpn.com). You can also use other VPN services.


* See also [Development Instructions Troubleshooting](/developer/development_instructions/troubleshooting)

---

## Testing with a remote device
Expand Down
4 changes: 1 addition & 3 deletions _docs/developer/getting_started/vm_install_using_vagrant_apple_silicon.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -171,9 +171,7 @@ the installation process.
If you do not see this message due to an error or the installation
has frozen, check out:

* [Installation Troubleshooting](/developer/getting_started/vm_install_using_vagrant#installation-troubleshooting)

* [Development Instructions Troubleshooting](/developer/development_instructions/troubleshooting)
* [Installation Troubleshooting](/developer/troubleshooting/installation_troubleshooting)

---

Expand Down
Loading