Merge branch 'main' into dark-mode-toggle

Author: bmcutler

Gemfile.lock

@@ -220,7 +220,7 @@ GEM
       gemoji (>= 3, < 5)
       html-pipeline (~> 2.2)
       jekyll (>= 3.0, < 5.0)
-    json (2.12.2)
+    json (2.13.0)
     kramdown (2.4.0)
       rexml
     kramdown-parser-gfm (1.1.0)

_docs/developer/development_instructions/automated_grading.md

@@ -118,12 +118,14 @@ number:
 
 ---
 
-## Debugging 
+## Debugging
 
 To debug new features for autograding, it can be helpful to run
 `submitty_autograding_shipper.py` and `submitty_autograding_worker.py`
 interactively and inspect the output.
 
+_NOTE: A cron job runs hourly to detect autograding shipper outages on the primary machine. To avoid interference during debugging, this job should be disabled before proceeding. See [Capture Cron Error Messages](/sysadmin/installation/system_customization#capture-cron-error-messages) for instructions on disabling the script._
+
 To do this:
 
 1. Stop the daemons (on each server, as appropriate)

_docs/developer/testing/install_php.md

@@ -8,7 +8,7 @@ you will need to have PHP installed on your host machine first.
 
 ### Linux & WSL:
 
-*If you're distro cannot find the correct package or installs the wrong version you may have to specify php7.0 in each package name*
+*If you're distro cannot find the correct package or installs the wrong version you may have to specify php8.1 in each package name*
 
 ```bash
 sudo apt-get update
@@ -23,6 +23,10 @@ If you are missing extensions you can install them with `PECL` which will be
 installed automatically with PHP, but you should have everything required by 
 default.
 
+### Windows
+
+Download [php 8.1](https://windows.php.net/download/) as a zip file under the thread safe category. Then extract the contents of the zip to a folder, and add the path to that folder to your path system variable. It's suggested that one extracts the contents of the zip to a folder called `php`, which can be put at `C:\php` for simplicity. You can then add `C:\php` to your path system environment variable.
+
 ------------- 
 
 Verify you have PHP installed correctly, submitty requires a version greater than 7.0

_docs/developer/testing/linting_static_analysis.md

@@ -58,7 +58,7 @@ The following instructions were tested for Windows:
 
 1. First, you will need PHP installed on your host system first. See [Installing PHP](/developer/testing/install_php)*
 
-2. Next, you will need [Composer](https://getcomposer.org/doc/00-intro.md) installed on your host system as well.
+2. Next, you will need [Composer](https://getcomposer.org/download/) installed on your host system as well.
 	During this install, you will need to change settings in a php.ini file. Change the settings the prompt recommends.
 
 3. Run ``composer global require slevomat/coding-standard`` and ``composer global require "squizlabs/php_codesniffer=*"`` inside your terminal.

_docs/developer/testing/php_unit_tests.md

@@ -9,33 +9,37 @@ To validate the unit behavior of the site code, we utilize
 
 ### Running PHP Unit Tests
 
-*You will need PHP installed on your host system first, see [Installing PHP](/developer/testing/install_php)*
+*If you are running on WSL and are seeing errors, remove `php` from the following commands.*
 
-To run the PHP unit test suite locally, `cd` to the `Submitty/site` directory and type:
+To run the PHP unit test suite in VM use the alias
 
-If you are running on WSL and are seeing errors, remove "`php`" from the following commands.
+```
+submitty_test php-unit
+```
+
+or
 
 ```
-php vendor/bin/phpunit
+sudo -u submitty_php php vendor/bin/phpunit
 ```
 
 To run just an individual class or test, you can use the `--filter` flag on PHPUnit.
 For example, to run the function `testInvalidProperty` would be
-`php vendor/bin/phpunit --filter testInvalidProperty` and running all
+`sudo -u submitty_php php vendor/bin/phpunit --filter testInvalidProperty` and running all
 of `AccessControlTester` would be
 `php vendor/bin/phpunit--filter AccessControlTester`. Be aware, filter
 can match against partial strings, so if you have two tests `testFoo` and `testFooBar`,
 running `--filter testFoo` will run them both. Alternatively, you can also directly run
 `phpunit` against a specific class by passing the path to the test class directly to
 `phpunit`, for example
-`php vendor/bin/phpunit tests/app/authentication/DatabaseAuthenticationTester.php` will run
+`sudo -u submitty_php php vendor/bin/phpunit tests/app/authentication/DatabaseAuthenticationTester.php` will run
 only the test methods in `DatabaseAuthenticationTester.php`.
 
 The two concepts above can be combined to run a specific test function in a specific
 class by doing:
 
 ```bash
-vendor/bin/phpunit --filter testFunction tests/app/path/to/TestClass.php
+sudo -u submitty_php php vendor/bin/phpunit --filter testFunction tests/app/path/to/TestClass.php
 ```
 
 You can pass in the `--debug` flag when using PHPUnit to see PHP output, this can be

_docs/sysadmin/installation/system_customization.md

@@ -28,10 +28,25 @@ You may want to back up more of `/var/local/submitty` to save configurations and
 
 ## Capture cron error messages
 
-The `submitty_daemon` user runs the [sbin/send_email.py](https://github.com/Submitty/Submitty/blob/master/sbin/send_email.py)
-script.  Console output from this script can be emailed to a sysadmin to help ensure that errors can be reported and addressed.
+To ensure the reliability of the various Submitty services, such as the WebSocket server, their health status is monitored and restarted hourly via the [sbin/repair_services.sh](https://github.com/Submitty/Submitty/blob/master/sbin/repair_services.sh) script run by the `submitty_daemon` user. This script leverages `systemctl` along with various health-check utility scripts to verify the active state of these services, triggering a restart if an inactive state is detected.
 
-The first line should be set as `MAILTO=` with a valid email address.  For example:
+Service failures can occur for various reasons, including unhandled exceptions, memory leaks, port binding issues, or OS-level disruptions such as resource exhaustion. All failures are logged with their relevant timestamp, source, and last output within the `/var/log/services` directory for the given day in the format `YYYYMMDD.txt`.
+
+To disable this auto-repair mechanism, comment out the relevant line in the source `.setup/submitty_crontab` file within your repository. Since the crontab is auto-generated during installation, any changes must be followed by a re-run of `submitty_install` to persist them.
+
+```bash
+# In .setup/submitty_crontab, comment out the repair_services.sh line:
+# 0 * * * * submitty_daemon   sudo /usr/local/submitty/sbin/repair_services.sh
+
+# Then re-apply the configuration:
+$ submitty_install
+```
+
+_Note: This mechanism should only be disabled with caution in production environments._
+
+The `submitty_daemon` user runs a variety of other scripts, such as [sbin/send_email.py](https://github.com/Submitty/Submitty/blob/master/sbin/send_email.py) to send pending emails every minute. Console output from these scripts can be emailed to a sysadmin to help ensure that errors can be reported and addressed.
+
+The first line of the relevant script should be set as `MAILTO=` with a valid email address, as shown below.
 ```
 [email protected]
 * * * * * python3 /usr/local/submitty/sbin/send_email.py

_docs/sysadmin/installation/version_notes/v20.08.00.md

@@ -16,7 +16,7 @@ requires the following edits:
 
 1. Locate your `php.ini` file.
 
-   _It is probably something like `/etc/php/7.2/fpm/php.ini`._
+   _It is probably something like `/etc/php/8.1/fpm/php.ini`._
 
    Note: You can run this command to print your specific version of php:
 
@@ -32,7 +32,7 @@ requires the following edits:
 3. Restart php fpm:
 
    ```
-   sudo systemctl restart php7.2-fpm
+   sudo systemctl restart php8.1-fpm
    ```
 
    Or more generally:

_docs/sysadmin/troubleshooting/system_debugging.md

@@ -62,6 +62,12 @@ redirect_from:
   /var/log/nginx/error.log
   ```
 
+* Look for errors in the daily service outage log
+
+  ```
+  /var/local/submitty/logs/services/YYYYMMDD.txt
+  ```
+
 * Check the SSL keys / certificates for apache & nginx.
   Look for ssl key & certificate files specified in the enabled
   `.conf` files for apache & nginx: