Difference between revisions of "Installation Manual for 2.17 on Oracle (and related) Linux"

From WeBWorK_wiki
Jump to navigation Jump to search
m
m
(32 intermediate revisions by the same user not shown)
Line 1: Line 1:
These instructions cover the installation of WeBWorK 2.17 from scratch onto an Oracle Linux 8 server. These instructions might work on related Linux distributions, but here and there the details may differ. It may help to cross-reference with other OS-specific installation guides at [[Manual Installation Guides]].
+
These instructions cover the installation of WeBWorK 2.17 from scratch onto a new Oracle Linux 8 server. These instructions might work on related Linux distributions such as RHEL 8, but the details may differ. Even on an Oracle 8 server, the template that was used while writing these instructions may have different packages and repositories than yours. So in some steps, you may find that you need to install some component that is missing first.
   
If you are just upgrading WeBWorK, especially if you already have existing WeBWorK courses, see [[Upgrading WeBWorK from 2.16 to 2.17]].
 
  +
It may help to cross-reference with other OS-specific installation guides at [[Manual Installation Guides]].
  +
  +
If you are merely upgrading WeBWorK, as opposed to a fresh installation, see [[Upgrading WeBWorK from 2.16 to 2.17]].
   
 
== Preliminaries ==
 
== Preliminaries ==
Line 17: Line 19:
 
When you get started, root and your personal user account should be present. It can be critical that you act as whatever user these instructions tell you to act as at each step. Do not act as root unless specifically instructed to.
 
When you get started, root and your personal user account should be present. It can be critical that you act as whatever user these instructions tell you to act as at each step. Do not act as root unless specifically instructed to.
   
Furthermore, when you will need to act as root, use <code>sudo bash</code>, <code>sudo su</code>, or <code>sudo &lt;command&gt;</code> exactly as the instructions say. In certain places, actually switching users to root when a mere <code>sudo someCommand</code> was indicated can result in bad things that will not become apparent until later in the installation.
+
Furthermore, when you need to act as root, you are advised to use <code>sudo bash</code>, <code>sudo su</code>, or <code>sudo &lt;command&gt;</code> exactly as the instructions say. Failing to do so can result in bad things that may not become apparent until later in the process.
   
 
=== Notation ===
 
=== Notation ===
Line 35: Line 37:
 
=== Check perl version ===
 
=== Check perl version ===
   
The Oracle distribution used for this installation write-up has perl 5.26.3. Check if perl is installed and what its version is.
+
For this write-up, the perl version was 5.26.3. Check if perl is installed and what its version is.
   
 
$ perl --version
 
$ perl --version
Line 55: Line 57:
 
Check that it is active with
 
Check that it is active with
   
$ sudo systemctl status mariadb
+
$ systemctl status mariadb
   
 
Now secure the server.
 
Now secure the server.
Line 74: Line 76:
 
You should see something close to:
 
You should see something close to:
   
Welcome to the MariaDB monitor. Commands end with ; or \g.
+
<b>Welcome to the MariaDB monitor. Commands end with ; or \g.</b>
 
...
 
...
 
...
 
...
Line 86: Line 88:
   
 
You should see a table with only three users: root, root and root, each with a different host.
 
You should see a table with only three users: root, root and root, each with a different host.
 
Now exit MariaDB
 
 
MariaDB [(none)]> exit
 
Bye
 
$
 
   
 
=== WeBWorK user and database ===
 
=== WeBWorK user and database ===
Line 98: Line 94:
   
 
In the steps below, we use <code>dAtAbAsE_pAsSwOrD</code> for this password. The obnoxious casing is to help you remember to replace that with what your actual password is.
 
In the steps below, we use <code>dAtAbAsE_pAsSwOrD</code> for this password. The obnoxious casing is to help you remember to replace that with what your actual password is.
 
$ sudo mysql
 
   
 
MariaDB [(none)]> CREATE DATABASE webwork;
 
MariaDB [(none)]> CREATE DATABASE webwork;
MariaDB [(none)]> CREATE USER 'webworkWrite'@'localhost' IDENTIFIED BY 'dAtAbAsE_pAsSwOrD';
+
MariaDB [(none)]> CREATE USER 'webworkWrite'@'localhost' IDENTIFIED BY '<b>dAtAbAsE_pAsSwOrD</b>';
 
MariaDB [(none)]> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, LOCK TABLES ON webwork.* TO 'webworkWrite'@'localhost';
 
MariaDB [(none)]> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, LOCK TABLES ON webwork.* TO 'webworkWrite'@'localhost';
 
MariaDB [(none)]> exit
 
MariaDB [(none)]> exit
Line 136: Line 130:
 
#LoadModule mpm_event_module modules/mod_mpm_event.so
 
#LoadModule mpm_event_module modules/mod_mpm_event.so
   
After the line with "LoadModule mpm_prefork_module", add the lines:
+
After the line <code>LoadModule mpm_prefork_module modules/mod_mpm_prefork.so</code> that you just uncommented, add the lines:
 
<IfModule mpm_prefork_module>
 
<IfModule mpm_prefork_module>
 
# For WeBWorK a rough rule of thumb is 5 MaxRequestWorkers per 1 GB of memory
 
# For WeBWorK a rough rule of thumb is 5 MaxRequestWorkers per 1 GB of memory
Line 148: Line 142:
 
Next we add configuration files that will add the mod_perl and Apache request modules.
 
Next we add configuration files that will add the mod_perl and Apache request modules.
 
# vim /etc/httpd/conf.modules.d/02-perl.conf
 
# vim /etc/httpd/conf.modules.d/02-perl.conf
Add the line <code>LoadModule perl_module modules/mod_perl.so</code> and save the file.
+
The line <code>LoadModule perl_module modules/mod_perl.so</code> may already be there. If so, good! If not, add that line and save the file. Then quit.
 
# vim /etc/httpd/conf.modules.d/apreq.conf
 
# vim /etc/httpd/conf.modules.d/apreq.conf
Add the line <code>LoadModule apreq_module modules/mod_apreq2.so</code> and save the file.
+
The line <code>LoadModule apreq_module modules/mod_apreq2.so</code> may already be there. If so, good! If not, add that line and save the file. Then quit.
   
 
Next we will make a few changes to Apache's default configuration. First, we back up the original.
 
Next we will make a few changes to Apache's default configuration. First, we back up the original.
Line 162: Line 156:
 
Also, uncomment and change the server name:
 
Also, uncomment and change the server name:
 
ServerName yourserverhost.edu
 
ServerName yourserverhost.edu
For this installation write-up, the server's fully qualified domain name was already set up. You can confirm if this is the case for you by running: <code>hostname; hostname --fqdn</code>. If your server's fully qualified domain name is not yet set up, run the command <code>sudo hostnamectl set-hostname &lt;webwork&gt;</code> where of course you should replace <code>&lt;webwork&gt;</code> by whatever your server's name is. Again, you can check these settings by running the commands <code>hostname; hostname --fqdn</code>. The first gives the server's fully qualified domain name (e.g. webwork.mydepartment.myschool.edu) and the second the server's name (e.g. webwork). Note that if your server can not find its fully qualified domain name, certain tools may not start.
+
For this installation write-up, the server's fully qualified domain name was already set up. You can confirm if this is the case for you by running: <code>hostname; hostname --fqdn</code>. If your server's fully qualified domain name is not yet set up, run the command <code>sudo hostnamectl set-hostname &lt;webwork&gt;</code> where of course you should replace <code>&lt;webwork&gt;</code> by whatever your server's name is. Again, you can check these settings by running the commands <code>hostname; hostname --fqdn</code>. The first gives the server's name (e.g. webwork) and the second gives the server's fully qualified domain name (e.g. webwork.mydepartment.myschool.edu). Note that if your server can not find its fully qualified domain name, certain tools may not start.
   
Then save the file and quit.
+
Save the file and quit.
  +
  +
Now disable the HTTP/2 module to avoid spamming the error log.
  +
# cd /etc/httpd/conf.modules.d
  +
# mv 10-h2.conf 10-h2.conf.bak
   
 
Finally, we need to make sure that the shared libraries have been properly identified
 
Finally, we need to make sure that the shared libraries have been properly identified
Line 177: Line 171:
   
 
Check its status just to confirm it's up.
 
Check its status just to confirm it's up.
$ sudo systemctl status httpd
+
$ systemctl status httpd
   
 
and test your server by connecting to your server from a web browser using the fully qualified domain name. You should see the '''Apache 2 Test Page''' indicating that Apache is running.
 
and test your server by connecting to your server from a web browser using the fully qualified domain name. You should see the '''Apache 2 Test Page''' indicating that Apache is running.
Line 195: Line 189:
   
 
This could take a while because it is a full installation. A full installation is probably unnecessary, but now that WeBWorK can use LaTeX to make images, it's simpler to just go ahead and install everything so you are not surprised later by a missing package.
 
This could take a while because it is a full installation. A full installation is probably unnecessary, but now that WeBWorK can use LaTeX to make images, it's simpler to just go ahead and install everything so you are not surprised later by a missing package.
  +
  +
At the end, you may see a message suggesting you add the path to LaTeX executables to your <code>$PATH</code>. You could do that now, either for your own shell profile or for all users by editing the appropriate <code>.basrc</code> or <code>.profile</code> file. Later we do this for the wwadmin user and it really doesn't matter for WeBWorK, which will be configured to know where LaTeX is anyway.
   
 
Now you might want to clean up the installation files.
 
Now you might want to clean up the installation files.
   
 
$ cd ..
 
$ cd ..
$ sudo rm -r install-tl*
+
$ rm -r install-tl*
   
 
=== Some graphics packages ===
 
=== Some graphics packages ===
Line 214: Line 210:
   
 
== Installing WeBWorK ==
 
== Installing WeBWorK ==
=== Downloading WeBWorK ===
 
  +
  +
=== wwadmin user ===
   
 
Create the wwadmin user and give that user a password that you store securely somehwere. Having a wwadmin user who is distinct from your personal user account will help in the future when others might take over management of the server, or assist with management.
 
Create the wwadmin user and give that user a password that you store securely somehwere. Having a wwadmin user who is distinct from your personal user account will help in the future when others might take over management of the server, or assist with management.
Line 223: Line 220:
 
Give wwadmin some secure password.
 
Give wwadmin some secure password.
   
Now edit wwadmin's .bashrc as we did with your personal user's .bashrc.
+
Now edit wwadmin's .bashrc.
   
 
$ sudo vim /home/wwadmin/.bashrc
 
$ sudo vim /home/wwadmin/.bashrc
Line 237: Line 234:
 
Save the file and quit.
 
Save the file and quit.
   
  +
=== Downloading WeBWorK ===
 
We are finally at the point where we can start downloading and installing WeBWorK itself. We will use Git to download WeBWorK from Github.
 
We are finally at the point where we can start downloading and installing WeBWorK itself. We will use Git to download WeBWorK from Github.
   
Line 281: Line 279:
 
# chmod -R g+w DATA ../courses htdocs/tmp logs tmp
 
# chmod -R g+w DATA ../courses htdocs/tmp logs tmp
 
# find DATA/ ../courses/ htdocs/tmp logs/ tmp/ -type d -a -exec chmod g+s {} \;
 
# find DATA/ ../courses/ htdocs/tmp logs/ tmp/ -type d -a -exec chmod g+s {} \;
  +
# chcon -R -t httpd_sys_content_t /opt/webwork/
 
# chcon -R -t httpd_sys_rw_content_t DATA ../courses htdocs/tmp logs tmp
 
# chcon -R -t httpd_sys_rw_content_t DATA ../courses htdocs/tmp logs tmp
   
The <code>chcon</code> line is specific to SELinux to give the apache user certain privileges in those folders that are denied by default. Here is some more SELinux stuff to run.
 
  +
  +
The <code>chcon</code> lines are specific to SELinux to give the apache user certain privileges in those folders that are denied by default. Here is some more SELinux stuff to run.
   
 
# yum install policycoreutils-python-utils
 
# yum install policycoreutils-python-utils
 
# semanage fcontext -a -t httpd_sys_content_t '/opt/webwork(/.*)?'
 
# semanage fcontext -a -t httpd_sys_content_t '/opt/webwork(/.*)?'
  +
# semanage fcontext -a -t httpd_sys_rw_content_t '/opt/webwork/webwork2/DATA(/.*)?'
 
# semanage fcontext -a -t httpd_sys_rw_content_t '/opt/webwork/courses(/.*)?'
 
# semanage fcontext -a -t httpd_sys_rw_content_t '/opt/webwork/courses(/.*)?'
# semanage fcontext -a -t httpd_sys_rw_content_t '/opt/webwork/webwork2/logs(/.*)?'
 
 
# semanage fcontext -a -t httpd_sys_rw_content_t '/opt/webwork/webwork2/htdocs/tmp(/.*)?'
 
# semanage fcontext -a -t httpd_sys_rw_content_t '/opt/webwork/webwork2/htdocs/tmp(/.*)?'
  +
# semanage fcontext -a -t httpd_sys_rw_content_t '/opt/webwork/webwork2/logs(/.*)?'
  +
# semanage fcontext -a -t httpd_sys_rw_content_t '/opt/webwork/webwork2/tmp(/.*)?'
 
# setsebool -P httpd_can_sendmail 1
 
# setsebool -P httpd_can_sendmail 1
 
# setsebool -P httpd_can_network_connect on
 
# setsebool -P httpd_can_network_connect on
Line 335: Line 337:
   
 
You may see some warning messages which you can safely ignore.
 
You may see some warning messages which you can safely ignore.
 
=== Configuring the Shell ===
 
 
To make working with WeBWorK easier, there are a couple of changes you can make to your shell environment.
 
 
Add the WeBWorK <code>bin</code> directory to your path. This will allow you to run WeBWorK command-line utilities without typing the full path to the utility. Go to your home directory and backup your <code>.bashrc</code> file
 
 
$ cd
 
$ cp .bashrc .bashrc.bak1
 
 
Now edit <code>.bashrc</code>. (Alternatively, these edits can be applied to <code>/etc/profile</code>, which will apply to all users.)
 
 
$ vim .bashrc
 
 
After the last line add the following three lines. But note that when we installed LaTeX earlier, it maybe landed in a different place. The "2022" and "x86_64-linux" might be different for you. You can run <code>ls -la /usr/local/texlive/*/bin/*/pdflatex</code> to identify the appropriate values.
 
 
export PATH=/usr/local/texlive/2022/bin/x86_64-linux:$PATH:/opt/webwork/webwork2/bin
 
export WEBWORK_ROOT=/opt/webwork/webwork2
 
export PG_ROOT=/opt/webwork/pg
 
 
Then save the file and Quit.
 
 
Close your Terminal Window and open a new one so the above changes
 
take effect. You can check that they have by
 
 
$ echo $PATH
 
$ echo $WEBWORK_ROOT
 
$ echo $PG_ROOT
 
   
 
=== Checking Module Dependencies ===
 
=== Checking Module Dependencies ===
Line 368: Line 342:
 
WeBWorK includes a script called <code>check_modules.pl</code> (in the directory <code>/opt/webwork/webwork2/bin</code>) that verifies that the needed programs and Perl modules are installed on your system. Run this script to make sure you have installed the required programs and Perl modules.
 
WeBWorK includes a script called <code>check_modules.pl</code> (in the directory <code>/opt/webwork/webwork2/bin</code>) that verifies that the needed programs and Perl modules are installed on your system. Run this script to make sure you have installed the required programs and Perl modules.
   
$ check_modules.pl apache2
+
$ /opt/webwork/webwork2/bin/check_modules.pl
   
 
You probably see a lot is missing, as indicated by <code>**</code>.
 
You probably see a lot is missing, as indicated by <code>**</code>.
   
In the executables section, the only thing that should be missing is pdf2svg, which we will not be using. If you see LaTeX executables missing, check that you correctly added the path to LaTeX executables in PATH as described above. If anything else is missing in the executables section, check if it was explicitly mentioned already in this guide, and that you completed those steps of the guide. Otherwise, maybe it just did not come with your OS installation and you should install it. You can search using <code>yum search someExecutable</code> and if found, install it using <code>yum install someExecutable</code>.
 
  +
In the executables section, you may see LaTeX executables missing along with dvipng. If so, it's probably just because we did not add the path to the LaTeX installation to this user's PATH. You can ignore that.
  +
  +
The other things that you may see missing is pdf2svg, which we will not be using.
  +
  +
If anything else is missing in the executables section, check if it was explicitly mentioned already in this guide, and that you completed those steps of the guide. Otherwise, maybe it just did not come with your OS installation and you should install it. You can search using <code>yum search someExecutable</code> and if found, install it using <code>yum install someExecutable</code>.
   
 
Now we will install the missing perl modules. While writing this guide, this missing ones are the ones indicated in the command a few lines below. You might need to modify.
 
Now we will install the missing perl modules. While writing this guide, this missing ones are the ones indicated in the command a few lines below. You might need to modify.
Line 381: Line 359:
 
cpan[1]>
 
cpan[1]>
   
Then run as follows, but compare the list of perl modules to the ones that were missing when you ran <code>check_modules</code>. Also, we are not using DBD::mysql even though that probably was missing. We are, however, going to need DBD::MariaDB, which was maybe not being checked for by <code>check_modules</code>. So include DBD::MariaDB, not DBD::mysql.
+
Then run as follows, but compare the list of perl modules to the ones that were missing when you ran <code>check_modules</code>. Also, we are not using DBD::mysql even though that was probably missing. We are, however, going to need DBD::MariaDB, which was possibly not checked by <code>check_modules</code>. So include DBD::MariaDB, not DBD::mysql.
   
Also, we need SQL::Abstract::Classic, which might not be checked for by <code>check_modules</code>.
+
Also, we need SQL::Abstract::Classic, which was possibly not checked by <code>check_modules</code>.
   
 
This may take a while! Keep an eye on it though because there may be occasional prompts asking if you want to conduct certain tests. Say yes to the tests unless you have a good reason not to.
 
This may take a while! Keep an eye on it though because there may be occasional prompts asking if you want to conduct certain tests. Say yes to the tests unless you have a good reason not to.
Line 418: Line 396:
   
 
Now we check that all necessary LaTeX packages have been installed. Earlier we did a full LaTeX installation, so everything should be there.
 
Now we check that all necessary LaTeX packages have been installed. Earlier we did a full LaTeX installation, so everything should be there.
$ check_latex
 
  +
$ sudo su wwadmin
  +
@ /opt/webwork/webwork2/bin/check_latex
 
and look for missing packages (you can ignore "No file check_latex.aux."). If the script displays "Compilation Success!", then all is good!
 
and look for missing packages (you can ignore "No file check_latex.aux."). If the script displays "Compilation Success!", then all is good!
   
 
=== Initialize WeBWorK config files ===
 
=== Initialize WeBWorK config files ===
   
$ sudo su wwadmin
 
 
@ cd /opt/webwork/webwork2/conf
 
@ cd /opt/webwork/webwork2/conf
 
@ cp webwork.apache2.4-config.dist webwork.apache2.4-config
 
@ cp webwork.apache2.4-config.dist webwork.apache2.4-config
Line 453: Line 431:
 
 
 
$ sudo su wwadmin
 
$ sudo su wwadmin
  +
@ cd /opt/webwork/webwork2/conf/
 
@ vim site.conf
 
@ vim site.conf
   
Line 472: Line 451:
   
 
Save the file and exit.
 
Save the file and exit.
 
Now stop and start apache.
 
$ sudo systemctl stop httpd
 
$ sudo systemctl start httpd
 
   
 
=== Javascript and css assets ===
 
=== Javascript and css assets ===
Line 486: Line 461:
 
@ npm install
 
@ npm install
   
The last <code>npm install</code> might appear to stall, but be patient. I got impatient and hit <code>&lt;ENTER&gt;</code> and then it appeared things sped up. Give that a try if you feel like it.
+
The last <code>npm install</code> might appear to stall, but be patient.
   
 
This installs javascript and css assets used by WeBWorK. Now you can return to your web browser and visit http://server_root_url/webwork2 (where "server_root_url" is your fully qualified domain) and reload the page. It should look good with no error messages.
 
This installs javascript and css assets used by WeBWorK. Now you can return to your web browser and visit http://server_root_url/webwork2 (where "server_root_url" is your fully qualified domain) and reload the page. It should look good with no error messages.
Line 497: Line 472:
 
@ /opt/webwork/webwork2/bin/addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin
 
@ /opt/webwork/webwork2/bin/addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin
   
  +
Restart apache:
  +
  +
@ exit
  +
$ sudo apachectl graceful
  +
$ sudo su wwadmin
  +
 
Now go to <code><nowiki>http://yourserver.yourschool.edu/webwork2</nowiki></code> and should see the WeBWorK home page with <code>Course Administration</code> listed at the top. Click on it and login with Username <code>admin</code> and Password <code>admin</code> . This first thing you should do is register your new WeBWorK installation. It's quick and easy, just click on <code>Register</code>. '''IMPORTANT''' The next thing you should do is click on <code>User Settings</code> and change <code>admin</code>'s password to something more secure than <code>admin</code>.
 
Now go to <code><nowiki>http://yourserver.yourschool.edu/webwork2</nowiki></code> and should see the WeBWorK home page with <code>Course Administration</code> listed at the top. Click on it and login with Username <code>admin</code> and Password <code>admin</code> . This first thing you should do is register your new WeBWorK installation. It's quick and easy, just click on <code>Register</code>. '''IMPORTANT''' The next thing you should do is click on <code>User Settings</code> and change <code>admin</code>'s password to something more secure than <code>admin</code>.
   
Line 510: Line 491:
 
# Now at the far right change <code>Permission Level</code> from <code>student</code> to <code>admin</code>
 
# Now at the far right change <code>Permission Level</code> from <code>student</code> to <code>admin</code>
 
# Then click <code>Take Action!</code>
 
# Then click <code>Take Action!</code>
 
At some point you will probably want to hide the <code>admin</code> course so that it is not listed on the WeBWorK home page. The <code>admin</code> course is used for administering WeBWorK and even though regular users can not log into it (you did change the <code>admin</code> password, didn't you!!), it's a little bit cleaner and safer to hide it from prying eyes.
 
 
To hide (or unhide) a course select <code>Hide Inactive courses</code> in the admin course and follow the directions. When hidden a course will not show up in the courses list on the WeBWorK home page. It will still appear in the Course Administration listing. If you do this you will still be able to access the <code>admin</code> course using the URL <code><nowiki>http://yourserver.yourschool.edu/webwork2/admin</nowiki></code> but you will not see a link for it on the WeBWorK home page <code><nowiki>http://yourserver.yourschool.edu/webwork2</nowiki></code> .
 
 
 
Now go to <code><nowiki>http://yourserver.yourschool.edu/webwork2</nowiki></code> and no course will be listed.
 
   
 
=== Open Problem Library ===
 
=== Open Problem Library ===
Line 523: Line 497:
   
 
Run the <code>OPL-update</code> script which will download the OPL metadata release and checkout the corresponding tag in the library as needed for the Library Browser in WeBWorK. Since this is a new installation, we do not have any OPL statistics to upload (see [[OPL_Problem_Statistics]]), so we run the two commands:
 
Run the <code>OPL-update</code> script which will download the OPL metadata release and checkout the corresponding tag in the library as needed for the Library Browser in WeBWorK. Since this is a new installation, we do not have any OPL statistics to upload (see [[OPL_Problem_Statistics]]), so we run the two commands:
  +
@ cd /opt/webwork/webwork2/bin/
 
@ export SKIP_UPLOAD_OPL_STATISTICS=1
 
@ export SKIP_UPLOAD_OPL_STATISTICS=1
@ OPL-update
+
@ ./OPL-update
   
 
If at some time in the future you want to upgrade the Problem Library, the process
 
If at some time in the future you want to upgrade the Problem Library, the process
 
is easy, see [[#Updating the OPL|Updating the OPL]]. Note that this is something you should do fairly often so that your library is up to date with
 
is easy, see [[#Updating the OPL|Updating the OPL]]. Note that this is something you should do fairly often so that your library is up to date with
 
new problems and bug fixes for old ones.
 
new problems and bug fixes for old ones.
 
   
   
Line 542: Line 516:
   
 
* You need to uncomment <code>$pg{specialPGEnvironmentVars}{latexImageSVGMethod} = "dvisvgm";</code> because the default is to use pdf2svg, which wee do not have, because it is very difficult (or impossible?) to install on Oracle. Anyway, dvisvgm makes better output as long as the version is new enough. And with our custom LaTeX installation, it should be new enough.
 
* You need to uncomment <code>$pg{specialPGEnvironmentVars}{latexImageSVGMethod} = "dvisvgm";</code> because the default is to use pdf2svg, which wee do not have, because it is very difficult (or impossible?) to install on Oracle. Anyway, dvisvgm makes better output as long as the version is new enough. And with our custom LaTeX installation, it should be new enough.
* Set values for <code>$institutionLogo</code>, <code>$institutionURL</code>, and <code>$institutionName</code>. For the logo, you need to place that image file in <code>/opt/webwork/webwork2/htdocs/themes/math4/images/</code>. (Later you can explore more intensive theme customization, but this is a significant step you can take in the meantime.)
+
* Set values for <code>$institutionLogo</code>, <code>$institutionURL</code>, and <code>$institutionName</code>. For the logo, you need to place that image file in <code>/opt/webwork/webwork2/htdocs/themes/math4/images/</code>. You may need to repeat the <code>chcon -R -t httpd_sys_content_t /opt/webwork/</code> command that we ran earlier so that apache can read and serve this file.
 
* Uncomment the line for <code>$webworkFiles{site_info}</code>. Visit <code>/opt/webwork/webwork2/htdocs/</code> and copy <code>site_info.txt</code> to <code>our_site_info.txt</code>, and then edit that file as you like. This is the information panel you see when you visit WeBWorK's landing page.
 
* Uncomment the line for <code>$webworkFiles{site_info}</code>. Visit <code>/opt/webwork/webwork2/htdocs/</code> and copy <code>site_info.txt</code> to <code>our_site_info.txt</code>, and then edit that file as you like. This is the information panel you see when you visit WeBWorK's landing page.
 
* If you plan to integrate WeBWorK into an LMS, you can uncomment <code>include("conf/authen_LTI.conf");</code>. However you should probably review [[LTI-Advanced Authentication]] first and follow up with other configuration settings.
 
* If you plan to integrate WeBWorK into an LMS, you can uncomment <code>include("conf/authen_LTI.conf");</code>. However you should probably review [[LTI-Advanced Authentication]] first and follow up with other configuration settings.
 
Now stop and start apache.
 
$ sudo systemctl stop httpd
 
$ sudo systemctl start httpd
 
   
 
=== Check configuration edits ===
 
=== Check configuration edits ===
Line 574: Line 544:
 
At some point you will probably want to "hide" <code>myTestCourse</code> from general view but you already know how to do that.
 
At some point you will probably want to "hide" <code>myTestCourse</code> from general view but you already know how to do that.
   
  +
== Housekeeping ==
  +
  +
=== Hide the admin and myTestCourse courses ===
  +
  +
Log into the admin course as admin with the new password you set earlier.
  +
  +
Select "Hide Inactive Courses" and select the courses you want to hide (admin and myTestCourse) and click "Hide Courses". If you go back to the WeBWorK Welcome page, you will see no courses listed. You can still access these courses directly by using their url. For example <nowiki>http://server_root_url/webwork2/admin</nowiki> and <nowiki>http://server_root_url/webwork2/myTestCourse</nowiki>.
  +
  +
=== Replace the default landing page ===
  +
You probably should replace <code>/var/www/html/index.html</code> with a page which redirects to the webwork course list at your site. Something like the following should work:
  +
  +
<html>
  +
<head>
  +
<META http-equiv="Pragma" content="no-cache">
  +
<META HTTP-EQUIV="Refresh" CONTENT="0;URL=https://mysite.mydomain.edu/webwork2/">
  +
<title>WeBWorK site - redirects to main page</title>
  +
</head>
  +
<body style="text-align: center;">
  +
You probably want to use the
  +
<a href="https://mysite.mydomain.edu/webwork2/">the WeBWorK list of courses page</a>
  +
</body>
  +
</html>
  +
  +
  +
  +
== More Tools ==
  +
  +
=== Install R ===
  +
  +
Some WeBWorK problems rely on R. If you are sure you will not need that, you can skip this.
  +
  +
The following sets up R on your WeBWorK server. If you'd like to have R running on a remote server, see [[R in WeBWorK]]. If you'd like to continue, run the following as root.
  +
  +
# dnf config-manager --add-repo https://yum.oracle.com/repo/OracleLinux/OL8/codeready/builder/x86_64
  +
# yum install R
  +
# Rscript -e 'install.packages("Rserve", repo="https://cran.rstudio.com")'
  +
# vim /usr/lib/systemd/system/rserve.service
  +
  +
Paste this content into what should be an empty file:
  +
  +
[Unit]
  +
Description=Rserve Binary R server
  +
After=network.target
  +
  +
[Service]
  +
Type=forking
  +
ExecStart=/usr/lib64/R/bin/Rserve --no-save
  +
Environment=R_HOME=/usr/lib64/R
  +
  +
[Install]
  +
WantedBy=multi-user.target
  +
  +
Save the file and exit.
  +
  +
# systemctl enable rserve
  +
  +
Now you can user <code>systemctl</code> to <code>start</code> and <code>stop</code> the <code>rserve</code> service as needed. And it is set up to start automatically on boot.
  +
  +
# vim /opt/webwork/webwork2/conf/localOverrides.conf
  +
  +
Uncomment the line
  +
  +
$pg{specialPGEnvironmentVars}{Rserve} = {host => "localhost"};
  +
  +
You should now be able to load questions which call R. There are a number of such questions already in the OPL, for example <code>Library/UBC/STAT/STAT300/hw07/stat300_hw07_q02.pg</code> (which can be found under Statistics -> Simple linear regression -> Hypothesis tests). If your R server is working properly, you should see a scatterplot in this question.
  +
  +
=== SSL ===
   
 
== More to come; this page is under construction ==
 
== More to come; this page is under construction ==

Revision as of 23:26, 20 September 2022

These instructions cover the installation of WeBWorK 2.17 from scratch onto a new Oracle Linux 8 server. These instructions might work on related Linux distributions such as RHEL 8, but the details may differ. Even on an Oracle 8 server, the template that was used while writing these instructions may have different packages and repositories than yours. So in some steps, you may find that you need to install some component that is missing first.

It may help to cross-reference with other OS-specific installation guides at Manual Installation Guides.

If you are merely upgrading WeBWorK, as opposed to a fresh installation, see Upgrading WeBWorK from 2.16 to 2.17.

Preliminaries

Read this section before getting started.

OS Users

These instructions reference four OS users.

  • You should have a personal account with sudo privileges.
  • root
  • apache
  • wwadmin

When you get started, root and your personal user account should be present. It can be critical that you act as whatever user these instructions tell you to act as at each step. Do not act as root unless specifically instructed to.

Furthermore, when you need to act as root, you are advised to use sudo bash, sudo su, or sudo <command> exactly as the instructions say. Failing to do so can result in bad things that may not become apparent until later in the process.

Notation

  • Code blocks that begin with $ should be run with your personal user account (which we assume has sudo privileges).
  • Code blocks that begin with # should be run as root (via either a root shell or switching users to root with sudo su).
  • Code blocks that begin with @ should be run as wwadmin (for which you can use sudo su wwadmin).

You are not intended to type the $, or #, or @ characters as part of the provided commands.

Assumptions

We assume that you already have Oracle installed (or a closely related Linux distribution) but that you haven't done much with yet.

We assume that you have a personal user account with sudo privileges.

Check perl version

For this write-up, the perl version was 5.26.3. Check if perl is installed and what its version is.

$ perl --version

If you have a different version, that could be OK and you can try to continue. But if you run into obstacles, it is possible that the perl version is responsible. The Installation Manual for 2.16 on RHEL8 installs a custom version of perl for this reason, and you may need to do that.

MariaDB

Installation

After logging in to your server:

$ sudo yum install mariadb-server mariadb-connector-c mariadb-connector-c-devel

Answer y if it asks if this is OK. (For the remainder of these instructions, such trivial details might be omitted.) Now fire it up.

$ sudo systemctl enable mariadb
$ sudo systemctl start mariadb

Check that it is active with

$ systemctl status mariadb

Now secure the server.

$ sudo mysql_secure_installation

This asks you for the database root password, which is nothing at this point. You should just hit <Enter>. Next there are five questions. Answer as indicated:

  • Set root password? n
  • Remove anonymous users? n
  • Disallow root login remotely? Y
  • Remove test database and access to it? Y
  • Reload privilege tables now? Y

Test that things work:

$ sudo mysql

You should see something close to:

Welcome to the MariaDB monitor.  Commands end with ; or \g.
...
...
...

MariaDB [(none)]> 

Now lets check the MariaDB users. To see the users, do the following

MariaDB> SELECT user,authentication_string,plugin,host FROM mysql.user;

You should see a table with only three users: root, root and root, each with a different host.

WeBWorK user and database

WeBWorK uses a single database, called webwork, for all courses. We will create the webwork database now. We also need to create a database user named webworkWrite and supply a password for that user. Use some secure password generator to generate a password that has no special characters. (Special characters in a database password sometimes cause trouble.) Write down this password because we will need it later.

In the steps below, we use dAtAbAsE_pAsSwOrD for this password. The obnoxious casing is to help you remember to replace that with what your actual password is.

MariaDB [(none)]> CREATE DATABASE webwork;
MariaDB [(none)]> CREATE USER 'webworkWrite'@'localhost' IDENTIFIED BY 'dAtAbAsE_pAsSwOrD';
MariaDB [(none)]> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, LOCK TABLES ON webwork.* TO 'webworkWrite'@'localhost';
MariaDB [(none)]> exit
Bye
$ 

where as we said replace dAtAbAsE_pAsSwOrD with the password you generated.

And again, hold on to this password. We will need to enter it into a WeBWorK configuration file later.


Apache 2 and mod_perl

Installation

Install apache (httpd) and mod_perl.

$ sudo yum install httpd mod_perl libapreq2 perl-libapreq2

Enable httpd service.

$ sudo systemctl enable httpd.service


Configuration Changes

Now enable the MPM-prefork module (and disable the MPM-event module)

$ sudo bash
# vim /etc/httpd/conf.modules.d/00-mpm.conf

Uncomment the mpm_prefork_module statement and comment out the mpm_event_module

LoadModule mpm_prefork_module modules/mod_mpm_prefork.so
#LoadModule mpm_event_module modules/mod_mpm_event.so

After the line LoadModule mpm_prefork_module modules/mod_mpm_prefork.so that you just uncommented, add the lines:

<IfModule mpm_prefork_module>
    # For WeBWorK a rough rule of thumb is 5 MaxRequestWorkers per 1 GB of memory
    MaxRequestWorkers         5
    MaxConnectionsPerChild    50
</IfModule>

where you should set MaxRequestWorkers depending on the amount of memory your server has using the above rule of thumb. Note that for very busy servers, you should observe you memory usage and return here tto adjust the above settings as necessary. Save the file and quit.

Next we add configuration files that will add the mod_perl and Apache request modules.

# vim /etc/httpd/conf.modules.d/02-perl.conf

The line LoadModule perl_module modules/mod_perl.so may already be there. If so, good! If not, add that line and save the file. Then quit.

# vim /etc/httpd/conf.modules.d/apreq.conf

The line LoadModule apreq_module modules/mod_apreq2.so may already be there. If so, good! If not, add that line and save the file. Then quit.

Next we will make a few changes to Apache's default configuration. First, we back up the original.

# cd /etc/httpd/conf
# cp httpd.conf httpd.conf.bak
# vim httpd.conf

Near the end, before "Supplemental configuration", add the line:

Timeout 1200 

Also, uncomment and change the server name:

ServerName yourserverhost.edu

For this installation write-up, the server's fully qualified domain name was already set up. You can confirm if this is the case for you by running: hostname; hostname --fqdn. If your server's fully qualified domain name is not yet set up, run the command sudo hostnamectl set-hostname <webwork> where of course you should replace <webwork> by whatever your server's name is. Again, you can check these settings by running the commands hostname; hostname --fqdn. The first gives the server's name (e.g. webwork) and the second gives the server's fully qualified domain name (e.g. webwork.mydepartment.myschool.edu). Note that if your server can not find its fully qualified domain name, certain tools may not start.

Save the file and quit.

Now disable the HTTP/2 module to avoid spamming the error log.

# cd /etc/httpd/conf.modules.d
# mv 10-h2.conf 10-h2.conf.bak

Finally, we need to make sure that the shared libraries have been properly identified

# ldconfig -v
# exit
$

Testing

You should now be able to start up the httpd service

$ sudo systemctl start httpd

Check its status just to confirm it's up.

$ systemctl status httpd

and test your server by connecting to your server from a web browser using the fully qualified domain name. You should see the Apache 2 Test Page indicating that Apache is running.

Install Miscellaneous Tools

LaTeX

The Oracle/RHEL package for texlive is likely to be a few years out of date, so we will install texlive directly. At the time of this installation write-up, the current version is 2022. In the steps that follow, replace "2022" with whatever is current. Note the very last option --paper=letter is only if you actually want letter to be the default paper size. Leave that off if you would like it to be A4.

$ cd /tmp # working directory of your choice
$ sudo yum install wget
$ wget https://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz
$ zcat install-tl-unx.tar.gz | tar xf -
$ cd install-tl-*/
$ sudo perl ./install-tl --no-interaction --paper=letter

This could take a while because it is a full installation. A full installation is probably unnecessary, but now that WeBWorK can use LaTeX to make images, it's simpler to just go ahead and install everything so you are not surprised later by a missing package.

At the end, you may see a message suggesting you add the path to LaTeX executables to your $PATH. You could do that now, either for your own shell profile or for all users by editing the appropriate .basrc or .profile file. Later we do this for the wwadmin user and it really doesn't matter for WeBWorK, which will be configured to know where LaTeX is anyway.

Now you might want to clean up the installation files.

$ cd ..
$ rm -r install-tl* 

Some graphics packages

Some graphics tools were installed with our new LaTeX installation: dvipng and dvisvgm. We need a few more.

$ sudo yum install gd-devel netpbm-progs ImageMagick

npm

And we will need Node Package Manager, npm:

$ sudo yum install npm

Installing WeBWorK

wwadmin user

Create the wwadmin user and give that user a password that you store securely somehwere. Having a wwadmin user who is distinct from your personal user account will help in the future when others might take over management of the server, or assist with management.

$ sudo useradd wwadmin
$ sudo passwd wwadmin

Give wwadmin some secure password.

Now edit wwadmin's .bashrc.

$ sudo vim /home/wwadmin/.bashrc

Add these lines to the end:

export PATH=/usr/local/texlive/2022/bin/x86_64-linux:$PATH:/opt/webwork/webwork2/bin
export WEBWORK_ROOT=/opt/webwork/webwork2
export PG_ROOT=/opt/webwork/pg

Except the "2022" and "x86_64-linux" may be different as before.

Save the file and quit.

Downloading WeBWorK

We are finally at the point where we can start downloading and installing WeBWorK itself. We will use Git to download WeBWorK from Github.

$ cd /opt
$ sudo mkdir webwork
$ sudo chown wwadmin:wwadmin webwork
$ sudo su wwadmin
@ cd webwork
@ git clone https://github.com/openwebwork/webwork2.git
@ git clone https://github.com/openwebwork/pg.git
@ git clone https://github.com/openwebwork/webwork-open-problem-library.git
@ mkdir courses
@ mkdir libraries
@ mv webwork-open-problem-library libraries 

Important Note. The above commands retrieve the main branch which gives the latest stable release of the software package (webwork2, pg, etc) with bug fixes. If a stable release newer than 2.17 exists, that will be downloaded and these instructions may be a little out of date. So it is a good idea to check before downloading. The best way to do that is to look at https://github.com/openwebwork/webwork2/blob/main/VERSION and https://github.com/openwebwork/pg/blob/main/VERSION.

Set Up Model Course

Now pull the model course from webwork2 into courses

@ cd /opt/webwork/webwork2/courses.dist
@ cp *.lst /opt/webwork/courses/
@ rsync -a modelCourse /opt/webwork/courses/

Setting Permissions

The PG installation directory and files should be owned by wwadmin and not writable by other users:

@ cd /opt/webwork/pg
@ chmod -R u+rwX,go+rX .

Most WeBWorK directories and files should also be owned by wwadmin and not writable by other users:

@ cd /opt/webwork/webwork2
@ chmod -R u+rwX,go+rX .
@ exit

Certain data directories need to be writable by the web server. These are DATA, courses, htdocs/tmp, logs, and tmp. Now we make these directories that need to be writable by the web server have apache as their group.

$ sudo bash
# cd /opt/webwork/webwork2/
# chgrp -R apache DATA ../courses htdocs/tmp logs tmp
# chmod -R g+w DATA ../courses htdocs/tmp logs tmp
# find DATA/ ../courses/ htdocs/tmp logs/ tmp/ -type d -a -exec chmod g+s {} \;
# chcon -R -t httpd_sys_content_t /opt/webwork/
# chcon -R -t httpd_sys_rw_content_t DATA ../courses htdocs/tmp logs tmp


The chcon lines are specific to SELinux to give the apache user certain privileges in those folders that are denied by default. Here is some more SELinux stuff to run.

# yum install policycoreutils-python-utils
# semanage fcontext -a -t httpd_sys_content_t '/opt/webwork(/.*)?' 
# semanage fcontext -a -t httpd_sys_rw_content_t '/opt/webwork/webwork2/DATA(/.*)?'
# semanage fcontext -a -t httpd_sys_rw_content_t '/opt/webwork/courses(/.*)?'
# semanage fcontext -a -t httpd_sys_rw_content_t '/opt/webwork/webwork2/htdocs/tmp(/.*)?'
# semanage fcontext -a -t httpd_sys_rw_content_t '/opt/webwork/webwork2/logs(/.*)?'
# semanage fcontext -a -t httpd_sys_rw_content_t '/opt/webwork/webwork2/tmp(/.*)?'
# setsebool -P httpd_can_sendmail 1
# setsebool -P httpd_can_network_connect on
# restorecon -vFR /opt

We also want to allow httpd to send pings during startup, which means we have to tell SELinux that's okay too. Create a new file called my-ping.te in wwadmin's home folder.

# vim /home/wwadmin/my-ping.te

Paste the following into the empty file:

module my-ping 1.0;

require {
       type httpd_t;
       class icmp_socket create;
       class rawip_socket { create getopt setopt write read };
       class capability net_raw;
}

#============= httpd_t ==============
allow httpd_t self:capability net_raw;
allow httpd_t self:icmp_socket create;
allow httpd_t self:rawip_socket { create getopt setopt write read };

Exit and save the file, then compile and install the policy:

# checkmodule -M -m -o my-ping.mod /home/wwadmin/my-ping.te
# semodule_package -o my-ping.pp -m my-ping.mod
# semodule -X 300 -i my-ping.pp


It is convenient to give WeBWorK administrators access to the five directories mentioned above as well, so they can perform administrative tasks such as removing temporary files, creating and editing courses from the command line, managing logs, and so on. We will add our user, wwadmin, to the apache group. Run the command

# usermod -a -G apache wwadmin
# exit

Compile color.c

$ cd /opt/webwork/pg/lib/chromatic
$ sudo yum install gcc
$ sudo su wwadmin
@ gcc color.c -o color
@ exit

You may see some warning messages which you can safely ignore.

Checking Module Dependencies

WeBWorK includes a script called check_modules.pl (in the directory /opt/webwork/webwork2/bin) that verifies that the needed programs and Perl modules are installed on your system. Run this script to make sure you have installed the required programs and Perl modules.

$ /opt/webwork/webwork2/bin/check_modules.pl

You probably see a lot is missing, as indicated by **.

In the executables section, you may see LaTeX executables missing along with dvipng. If so, it's probably just because we did not add the path to the LaTeX installation to this user's PATH. You can ignore that.

The other things that you may see missing is pdf2svg, which we will not be using.

If anything else is missing in the executables section, check if it was explicitly mentioned already in this guide, and that you completed those steps of the guide. Otherwise, maybe it just did not come with your OS installation and you should install it. You can search using yum search someExecutable and if found, install it using yum install someExecutable.

Now we will install the missing perl modules. While writing this guide, this missing ones are the ones indicated in the command a few lines below. You might need to modify.

$ sudo perl -MCPAN -e shell

You might be prompted to auto-configure. Say yes. You should be in the cpan shell and see the prompt:

cpan[1]> 

Then run as follows, but compare the list of perl modules to the ones that were missing when you ran check_modules. Also, we are not using DBD::mysql even though that was probably missing. We are, however, going to need DBD::MariaDB, which was possibly not checked by check_modules. So include DBD::MariaDB, not DBD::mysql.

Also, we need SQL::Abstract::Classic, which was possibly not checked by check_modules.

This may take a while! Keep an eye on it though because there may be occasional prompts asking if you want to conduct certain tests. Say yes to the tests unless you have a good reason not to.

cpan[1]> install Array::Utils CGI CGI::Cookie Class::Accessor Data::Dump Data::UUID Date::Format Date::Parse DateTime DBD::MariaDB DBI Email::Address::XS Email::Sender::Simple Email::Sender::Transport::SMTP Email::Stuffer Exception::Class File::Find::Rule GD HTML::Entities HTML::Scrubber HTML::Tagset HTML::Template HTTP::Async IO::Socket::SSL Iterator Iterator::Util JSON JSON::MaybeXS Locale::Maketext::Lexicon LWP::Protocol::https Net::IP Net::LDAPS Net::OAuth Net::SSLeay PadWalker Path::Class PHP::Serialization Pod::WSDL SOAP::Lite SQL::Abstract::Classic Statistics::R::IO String::ShellQuote Template Text::CSV Tie::IxHash Time::Zone Types::Serialiser UUID::Tiny XML::Parser XML::Parser::EasyTree XML::Simple XML::Writer XMLRPC::Lite YAML::XS Apache2::Request

At a certain point, you may see a prompt with a message about JSON::XS possibly not working with the version of perl we are using. For this write-up, the perl version is 5.26, and everything worked out fine.

You may see questions about the XS Stash module. You can answer yes.

You may see questions like "Do you want to install 'xml_...'. You can answer yes.

You might encounter this message:

 Your Perl is configured to link against libgdbm, 
 but libgdbm.so was not found.
 You could just symlink it to /lib64/libgdbm.so.6.0.0

I hit q and it was fine.

When it's all done, you can exit.

cpan[2]> exit
$

Now run check_modules.pl apache2 as before to see if something didn't work. You may see that Apache2::Request is found, but failed to load. This is probably OK. I believe it means that check_modules is missing some configuration detail that WeBWorK itself will have in place.

You might also see some warning messages like

Prototype mismatch: sub main::from_json: none vs ($@) at (eval 188) line 2.
Prototype mismatch: sub main::to_json: none vs ($@) at (eval 188) line 2.

This seems to be a known bug in libjson-perl and can be safely ignored.

Check LaTeX dependencies

Now we check that all necessary LaTeX packages have been installed. Earlier we did a full LaTeX installation, so everything should be there.

$ sudo su wwadmin
@ /opt/webwork/webwork2/bin/check_latex

and look for missing packages (you can ignore "No file check_latex.aux."). If the script displays "Compilation Success!", then all is good!

Initialize WeBWorK config files

@ cd /opt/webwork/webwork2/conf
@ cp webwork.apache2.4-config.dist webwork.apache2.4-config
@ cp site.conf.dist site.conf

Now edit site.conf and enter your value for $server_root_url.

@ vim site.conf

After entering a value for $server_root_url as the comments in the file describe. save the file and exit.

@ cp localOverrides.conf.dist localOverrides.conf
@ exit
$ sudo ln -s /opt/webwork/webwork2/conf/webwork.apache2.4-config /etc/httpd/conf.d/webwork.conf

Copy WeBWorK's icon file favicon.ico to Apache's www directory. Also, create a dummy index.html file here to avoid complaints from apache.

$ sudo cp /opt/webwork/webwork2/htdocs/favicon.ico /var/www/html
$ sudo touch /var/www/html/index.html


Now stop and start apache.

$ sudo systemctl stop httpd
$ sudo systemctl start httpd

You should be able to visit WeBWorK in a web browser now, although it will show errors. In a web browser, visit http://server_root_url/webwork2, where server_root_url is what you used above in site.conf.

More site.conf configuration

Edit site.conf again.

$ sudo su wwadmin
@ cd /opt/webwork/webwork2/conf/
@ vim site.conf

The most critical thing is to enter that password for the database user webworkWrite. Earlier in this guide we called that "dAtAbAsE_pAsSwOrD". You should have it written down somewhere, and you need to enter that in site.conf where $database_password is defined.

Our custom LaTeX installation landed at /usr/local/texlive/YEAR/bin/PLATFORM/, where YEAR and PLATFORM are something specific. You can run ls -la /usr/local/texlive/*/bin/*/pdflatex to determine exactly where on your system. Change the paths on the following to reflect this location.

  • $externalPrograms{latex} (Keep the --no-shell-escape option in place!)
  • $externalPrograms{pdflatex} (Keep the --no-shell-escape option in place!)
  • $externalPrograms{dvipng}
  • $externalPrograms{dvisvgm}

Scroll back to the top of site.conf and work your way down, reviewing all of the settings. Here are the ones that you probably want/need to set:

  • $webwork_server_admin_email
  • $mail{smtpServer}
  • $mail{smtpSender}
  • $mail{set_return_path}
  • $siteDefaults{timezone}

Save the file and exit.

Javascript and css assets

Earlier we installed npm. Visit the htdocs folder in the webwork2 and pg repositories, and run npm install like this:

@ cd /opt/webwork/webwork2/htdocs
@ npm install
@ cd /opt/webwork/pg/htdocs
@ npm install

The last npm install might appear to stall, but be patient.

This installs javascript and css assets used by WeBWorK. Now you can return to your web browser and visit http://server_root_url/webwork2 (where "server_root_url" is your fully qualified domain) and reload the page. It should look good with no error messages.

Create the admin course

WeBWorK has one "course" named admin that serves as a GUI for course management. We need to create that course.

@ cd /opt/webwork/courses
@ /opt/webwork/webwork2/bin/addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin

Restart apache:

@ exit
$ sudo apachectl graceful
$ sudo su wwadmin

Now go to http://yourserver.yourschool.edu/webwork2 and should see the WeBWorK home page with Course Administration listed at the top. Click on it and login with Username admin and Password admin . This first thing you should do is register your new WeBWorK installation. It's quick and easy, just click on Register. IMPORTANT The next thing you should do is click on User Settings and change admin's password to something more secure than admin.

Unless you choose otherwise, users with admin privileges in the admin course (i.e. WeBWorK administrators) will automatically be added to new courses with admin privileges and the same password as in the admin course. Initially the only such user is admin (hopefully you are not confused by the fact that the course admin has a user named admin). It's usually convenient make yourself a WeBWorK administrator. To do this (assuming you are logged in as admin to the admin course at http://yourserver.yourschool.edu/webwork2/admin )

  1. Click on Classlist Editor in the left panel
  2. Click the Add tag and click Take Action!
  3. Enter the appropriate information (you can use your Login Name as the Student ID if you want and also you can leave the last three items blank) and click Add Students
  4. Click on Classlist Editor in the left panel again
  5. When you enter a new user, by default their Student ID is used as their password. We'll change this now.
  6. Select yourself with a check mark and click the Password tag and click Take Action!. (Note as a safely mechanism you can not change the password for the user you are logged in as, currently admin, this way)
  7. Enter the password and then click Take Action!
  8. Finally give yourself admin privileges by selecting yourself with a check mark, clicking the Edit tag and then clicking Take Action! (or by just clicking on the "pencil" next to your login name which is a much faster way to edit classlist data for a single user)
  9. Now at the far right change Permission Level from student to admin
  10. Then click Take Action!

Open Problem Library

The Open Problem Library consists of both WeBWorK problems and methods for searching and selecting problems. Also it contains as sub libraries many of the other standard libraries. We have to load a database for searching it.

Run the OPL-update script which will download the OPL metadata release and checkout the corresponding tag in the library as needed for the Library Browser in WeBWorK. Since this is a new installation, we do not have any OPL statistics to upload (see OPL_Problem_Statistics), so we run the two commands:

@ cd /opt/webwork/webwork2/bin/
@ export SKIP_UPLOAD_OPL_STATISTICS=1
@ ./OPL-update

If at some time in the future you want to upgrade the Problem Library, the process is easy, see Updating the OPL. Note that this is something you should do fairly often so that your library is up to date with new problems and bug fixes for old ones.


localOverrides.conf

Edit localOverrides.conf.

@ cd /opt/webwork/webwork2/conf
@ vim localOverrides.conf

Make your way through this file to configure the behavior of WeBWorK itself. (As opposed to site.conf, which is more for telling WeBWorK about how your server is configured.) Here are a few things to draw your attention to.

  • You need to uncomment $pg{specialPGEnvironmentVars}{latexImageSVGMethod} = "dvisvgm"; because the default is to use pdf2svg, which wee do not have, because it is very difficult (or impossible?) to install on Oracle. Anyway, dvisvgm makes better output as long as the version is new enough. And with our custom LaTeX installation, it should be new enough.
  • Set values for $institutionLogo, $institutionURL, and $institutionName. For the logo, you need to place that image file in /opt/webwork/webwork2/htdocs/themes/math4/images/. You may need to repeat the chcon -R -t httpd_sys_content_t /opt/webwork/ command that we ran earlier so that apache can read and serve this file.
  • Uncomment the line for $webworkFiles{site_info}. Visit /opt/webwork/webwork2/htdocs/ and copy site_info.txt to our_site_info.txt, and then edit that file as you like. This is the information panel you see when you visit WeBWorK's landing page.
  • If you plan to integrate WeBWorK into an LMS, you can uncomment include("conf/authen_LTI.conf");. However you should probably review LTI-Advanced Authentication first and follow up with other configuration settings.

Check configuration edits

Since we have edited site.conf and localOverrides.conf and these are critical files, it would be a good idea to run

@ cd /opt/webwork/webwork2/conf
@ diff site.conf.dist site.conf
@ diff localOverrides.conf.dist localOverrides.conf

and check that you haven't made any mistakes (e.g. by introducing an inadvertent line break, etc.). If there are any mistakes, correct them. Any time you change either of these files you must restart the Apache webserver in order for some of these changes to take effect.

Now log into the admin course ( http://yourserver.yourschool.edu/webwork2/admin ) as yourself or admin and

  1. click on Add Course
  2. For Course ID enter myTestCourse
  3. For Course Title enter My Test Course
  4. Enter your institution
  5. Leave Add WeBWorK administrators to new course and Copy simple configuration file to new course checked
  6. Add an additional instructor if you wish
  7. Copy templates from: modelCourse (the default action)
  8. Click on Add Course
  9. Click Log into myTestCourse

and log in either as admin or yourself (if you added yourself as an additional instructor above).

At some point you will probably want to "hide" myTestCourse from general view but you already know how to do that.

Housekeeping

Hide the admin and myTestCourse courses

Log into the admin course as admin with the new password you set earlier.

Select "Hide Inactive Courses" and select the courses you want to hide (admin and myTestCourse) and click "Hide Courses". If you go back to the WeBWorK Welcome page, you will see no courses listed. You can still access these courses directly by using their url. For example http://server_root_url/webwork2/admin and http://server_root_url/webwork2/myTestCourse.

Replace the default landing page

You probably should replace /var/www/html/index.html with a page which redirects to the webwork course list at your site. Something like the following should work:

 <html>
 <head>
   <META http-equiv="Pragma" content="no-cache">
   <META HTTP-EQUIV="Refresh" CONTENT="0;URL=https://mysite.mydomain.edu/webwork2/">
   <title>WeBWorK site - redirects to main page</title>
 </head>
 <body style="text-align: center;">
   You probably want to use the
   <a href="https://mysite.mydomain.edu/webwork2/">the WeBWorK list of courses page</a>
 </body>
 </html>


More Tools

Install R

Some WeBWorK problems rely on R. If you are sure you will not need that, you can skip this.

The following sets up R on your WeBWorK server. If you'd like to have R running on a remote server, see R in WeBWorK. If you'd like to continue, run the following as root.

# dnf config-manager --add-repo https://yum.oracle.com/repo/OracleLinux/OL8/codeready/builder/x86_64
# yum install R
# Rscript -e 'install.packages("Rserve", repo="https://cran.rstudio.com")'
# vim /usr/lib/systemd/system/rserve.service

Paste this content into what should be an empty file:

[Unit]
Description=Rserve Binary R server
After=network.target

[Service]
Type=forking
ExecStart=/usr/lib64/R/bin/Rserve --no-save
Environment=R_HOME=/usr/lib64/R

[Install]
WantedBy=multi-user.target

Save the file and exit.

# systemctl enable rserve

Now you can user systemctl to start and stop the rserve service as needed. And it is set up to start automatically on boot.

# vim /opt/webwork/webwork2/conf/localOverrides.conf

Uncomment the line

$pg{specialPGEnvironmentVars}{Rserve} = {host => "localhost"};

You should now be able to load questions which call R. There are a number of such questions already in the OPL, for example Library/UBC/STAT/STAT300/hw07/stat300_hw07_q02.pg (which can be found under Statistics -> Simple linear regression -> Hypothesis tests). If your R server is working properly, you should see a scatterplot in this question.

SSL

More to come; this page is under construction