[Documentation:System] HTTP/2 Changes (#438)

Related Submitty/Submitty#7940

---------

Co-authored-by: Preston Carman <[email protected]>
Co-authored-by: Viane Matsibekker <[email protected]>
Co-authored-by: Chris Reed <[email protected]>
Co-authored-by: Barb Cutler <Barb Cutler>

Author: 4 people

_docs/developer/developing_the_php_site/websocket.md

@@ -88,3 +88,22 @@ const ws = new WebSocket('ws://localhost:1511/ws');
 ws.onmessage = (data) => console.log(data);
 ws.send('ping');
 ```
+
+### Debugging WebSocket in HTTPS
+
+Note that most browsers do not trust WebSocket traffics with self-
+signed certificates.  If you are dealing with WebSocket related features,
+there are some workarounds:
+
+- Copy the certificates from your VM and trust it on your host system;
+
+- OR, Trust/Ignore the certificates on your browser;
+
+- OR, Downgrade to HTTP/1.1 without TLS using `bash /usr/local/submitty/GIT_CHECKOUT/Submitty/.setup/dev-upgrade-h2.sh down`.
+
+You could try following to trust/ignore certificates on your browser:
+
+- For Chrome, start Chrome with `--ignore-certificate-errors`.
+
+- For Firefox, trust the certificate when the warning pops up;
+  And go to `https://localhost:8443/ws` and hit trust again.

_docs/developer/getting_started/vm_install_using_vagrant.md

@@ -14,9 +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. 
-The instructions below are for VirtualBox.  While alternatively using 
-VMWare should work, we have not tested this, and do not provide these 
+__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.
 
 ---
@@ -50,15 +50,15 @@ If you using an Intel-based Mac, you will follow the instructions below._
    Leaving it enabled will force VirtualBox to use the Hyper-V
    backend, which will be slower and can cause instability in the
    VM.
-   
+
    **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.
-   
+
    **Note:**
-   Installing WSL2 may also reconfigure your OS to use Hyper-V or Windows hypervisor 
+   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.
 
@@ -106,7 +106,7 @@ If you using an Intel-based Mac, you will follow the instructions below._
 
    4. Be sure to choose **Hardware Virtualization** in the **System -> Acceleration** settings of the virtual machine you are using.
 
-   **NOTE** 
+   **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.
@@ -153,7 +153,7 @@ Below are quick steps to get everything installed and running.
    ```
    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
    [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.
@@ -211,24 +211,42 @@ Below are quick steps to get everything installed and running.
    NO_SUBMISSIONS=1 vagrant up
    ```
 
-   On Windows, you will have to first set the environment variable `NO_SUBMISSIONS` to 1
-   which lasts for the session of that console, then call vagrant up.
-   
+   On Windows `cmd`, you will have to first set the environment variable
+   `NO_SUBMISSIONS` to 1 which lasts for the session of that console,
+   then call vagrant up.
+
    ```
    SET NO_SUBMISSIONS=1
    vagrant up
    ```
 
-   If you want to unset the variable later, you can do
+   On PowerShell, you will have to set the environment variable differently:
+
+   ```pwsh
+   $Env:NO_SUBMISSIONS=1
+   vagrant up
+   ```
+
+   If you want to unset the variable later in `cmd`, you can do
    ```
    SET NO_SUBMISSIONS=
    ```
 
+   Or in PowerShell,
+   ```pwsh
+   Remove-Item Env:\NO_SUBMISSIONS
+   ```
+
    Similarly, you can check that the variable is set by doing
    ```
    SET NO_SUBMISSIONS
    ```
 
+
+   Or in PowerShell,
+   ```pwsh
+   $Env:NO_SUBMISSIONS
+   ```
 8. When the install has completed, you should see the message:
    ```
    #####################################################################
@@ -279,10 +297,10 @@ Below are quick steps to get everything installed and running.
      grades details by uploading sample submissions from the Submitty
      repository, located in one of these these directories:
 
-     For the "tutorial" course:  
+     For the "tutorial" course:
      <https://github.com/Submitty/Tutorial/tree/main/examples>
 
-     For the "sample" course:  
+     For the "sample" course:
      <https://github.com/Submitty/Submitty/tree/master/more_autograding_examples>
 
 2. When the VM is "up", you can connect from your host computer to the
@@ -312,7 +330,7 @@ Below are quick steps to get everything installed and running.
     ```
 
     If it asks for password, it should be "vagrant"
-    and then 
+    and then
 
     ```sh
     sudo su
@@ -354,7 +372,7 @@ Below are quick steps to get everything installed and running.
 
 
 1. When you take a break from Submitty development work, you can
-   suspend the Submitty VM to to save resources (CPU and battery) on
+   suspend the Submitty VM to save resources (CPU and battery) on
    your host machine.
 
    ```
@@ -444,3 +462,20 @@ Below are quick steps to get everything installed and running.
    This has been tested with Blink for iOS and Termius for iOS (also available on Android, untested).
 
 6. Navigate to `localhost:1511` on the remote device.
+
+---
+
+## Developing in HTTPS
+
+For *developers* who need to upgrade to HTTP/2 in their development environments,
+please follow the step below:
+
+- Run `bash /usr/local/submitty/GIT_CHECKOUT/Submitty/.setup/dev-upgrade-h2.sh up`.
+
+   After a successful execution, please use `https://` instead of `http://`.
+
+- To downgrade to HTTP/1.1, run `bash /usr/local/submitty/GIT_CHECKOUT/Submitty/.setup/dev-upgrade-h2.sh down`.
+
+The script should automatically handle the upgrading and issuing a self-signed
+certificate.  If your browser complains about the security, please head to
+[WebSocket](/developer/developing_the_php_site/websocket).

_docs/sysadmin/installation/system_customization.md

@@ -359,6 +359,11 @@ Refer to [this](/student/communication/markdown) to learn more about markdown.
 
 
 
+## Changing the multi-processing module of Apache2, Enabling HTTP2
+
+Please refer to [this sysadmin action](/sysadmin/installation/version_notes/v23.12.02) page.
+
+
 ## Preferred Name Change Logging
 
 In the interests of diversity, Submitty provides for users to set a preferred name should it be different from their legal name.  This feature can be abused, so changes to a user's preferred name is recorded into Postgresql's log for review.  To make it easier to locate these logged messages, a sysadmin tools script, `pnc_compile.pl`, is provided to fetch the preferred name change logs from Postgresql and compile them into a human readable report.
@@ -381,4 +386,5 @@ In the interests of diversity, Submitty provides for users to set a preferred na
   * Postgresql's log is typically owned by `root`, so it is mandatory to run the script as `root`.
   * Be sure to set execute permission on the script.
   * The script will parse Postgresql's log *by the current day's datestamp*, so it is intended that the script is run once per day.
-  * Alternatively, if you wish to schedule the crontab for overnight after 12AM, you can set the `-y` or `--yesterday` argument so the script will intentionally parse Postgresql's log by the *previous* day's datestamp.  e.g. `/path/to/pnc_compile.pl -y`
+  * Alternatively, if you wish to schedule the crontab for overnight after 12AM, you can set the `-y` or `--yesterday` argument so the script will intentionally parse Postgresql's log by the *previous* day's datestamp.  e.g. `/path/to/pnc_compile.pl -y`
+

_docs/sysadmin/installation/version_notes/v23.12.02.md

@@ -0,0 +1,88 @@
+---
+title:  v23.12.02 > Apache2 HTTP/2 Support
+category: System Administrator > Installation Version Notes
+redirect_from:
+  - /system_admin/version_notes/v23.12.02
+---
+
+Release [v23.12.02](https://github.com/Submitty/Submitty/releases/v23.12.02)
+includes an update to the Apache2 server's module and configuration to
+disable `php8.1` and `mpm_prefork` and enable `mpm_event` and `http2`.
+Note:  Submitty uses `php8.1-fpm` NOT `php8.1`.
+
+
+1. If you have load balancers and firewalls in front of the Apache
+   server for Submitty, please make sure they support HTTP/2
+   redirections.
+
+2. Disable `php8.1` and `mpm_prefork`:
+
+   ```
+   a2dismod php8.1 mpm_prefork
+   ```
+
+3. Enable `mpm_event` and `http2`:
+
+   ```
+   a2enmod mpm_event http2
+   ```
+
+4. If you are not already using TLS/SSL HTTPS encryption for Submitty,
+   we strongly recommend enabling it.  See 
+   [System Administrator Installation Instructions](https://submitty.org/sysadmin/installation/index).
+
+5. Review your current performance tuning for `php-fpm`.  
+   ```
+   /etc/php/8.1/fpm/pool.d/submitty.conf
+   ```
+   You will probably not need to change these settings.
+
+6. With the switch from `mpm_prefork` to `mpm_event`, you will probably want to take any customization from this file:
+   ``` 
+   /etc/apache2/mods-available/mpm_prefork.conf
+   ```
+
+   And adapt it to this file:
+   ```
+   /etc/apache2/mods-available/mpm_event.conf
+   ```
+   
+6. Final check for Apache2's configuration;
+   ```sh
+   apachectl -t
+   ```
+
+7. Reload Apache2 to apply changes.
+
+   ```
+   sudo systemctl restart apache2.service
+   sudo systemctl restart php8.1-fpm
+   ```
+
+8. Run the update script.
+
+   ```
+   sudo /usr/local/submitty/.setup/INSTALL_SUBMITTY.sh
+   ```
+   
+---
+
+NOTE:  If you need to downgrade from HTTP/2 back to HTTP/1.1 and re-enable `mpm_prefork`,
+please follow the steps below:
+
+1. Disable `http2` and `mpm_event`:
+
+   ```
+   a2dismod http2 mpm_event
+   ```
+
+2. Enable `mpm_prefork`:
+
+   ```
+   a2enmod mpm_prefork
+   ```
+
+3. Alternatively, if the PHP does not use a `fpm` server, consider enabling
+   `php8.1` by `a2enmod php8.1`.
+
+

navtreedata.js

@@ -145,6 +145,7 @@ var NAVTREE =
                 [ "Update Submitty", "/sysadmin/installation/update_submitty", null ],
                 [ "Version Notes", "/sysadmin/installation/version_notes/index", [
                     [ "Overview", "/sysadmin/installation/version_notes/index", null],
+                    [ "v23.12.02", "/sysadmin/installation/version_notes/v23.12.02", null ],
                     [ "v23.07.00", "/sysadmin/installation/version_notes/v23.07.00", null ],
                     [ "v23.03.01", "/sysadmin/installation/version_notes/v23.03.01", null ],
                     [ "v22.06.00", "/sysadmin/installation/version_notes/v22.06.00", null ],