diff --git a/_docs/developer/developing_the_php_site/websocket.md b/_docs/developer/developing_the_php_site/websocket.md index 53867e39..bb9c0217 100644 --- a/_docs/developer/developing_the_php_site/websocket.md +++ b/_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. diff --git a/_docs/developer/getting_started/vm_install_using_vagrant.md b/_docs/developer/getting_started/vm_install_using_vagrant.md index 19a0bd54..43c1c9cc 100644 --- a/_docs/developer/getting_started/vm_install_using_vagrant.md +++ b/_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: - For the "sample" course: + For the "sample" course: 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). diff --git a/_docs/sysadmin/installation/system_customization.md b/_docs/sysadmin/installation/system_customization.md index 27e9a2dd..0a197ced 100644 --- a/_docs/sysadmin/installation/system_customization.md +++ b/_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` \ No newline at end of file + * 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` + diff --git a/_docs/sysadmin/installation/version_notes/v23.12.02.md b/_docs/sysadmin/installation/version_notes/v23.12.02.md new file mode 100644 index 00000000..2c530eff --- /dev/null +++ b/_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`. + + diff --git a/navtreedata.js b/navtreedata.js index 65345c19..bb74d8a8 100644 --- a/navtreedata.js +++ b/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 ],