Difference between revisions of "Installation Manual for 2.4 on Fedora 9"

From WeBWorK_wiki
Jump to navigation Jump to search
(tag as Historical & Deprecated, add link to Github page)
 
(52 intermediate revisions by one other user not shown)
Line 1: Line 1:
{|class="messagebox" style="background-color:#FFFFCC"
 
  +
{{Historical}}
|-
 
| This is a work in progress. I am in the process of modifying the instructions for installing WeBWorK 2.3 on Fedora Core 7 to cover the case of installing WeBWorK 2.4. on Fedora 9. You should not rely on these instructions until this warning message is removed.
 
|}
 
   
  +
{{Deprecated|2.6. For up-to-date information view [[Github]]}}
  +
  +
  +
''See also:'' [[History of WeBWorK version control]]
   
   
Line 26: Line 27:
 
===Installation DVD ===
 
===Installation DVD ===
 
Obtain the installation DVD/CD set. Connect to
 
Obtain the installation DVD/CD set. Connect to
http://fedoraproject.org/wiki/Distribution/Download for information. For example you can use wxDownload Fast or BitTorrent to download an ISO image of the installation DVD and then burn your own installation DVD. If you download ISO images, make sure that you verify the integrity of the downloaded files by comparing the SHA1 checksums of the downloaded files with the SHA1 checksums listed at http://fedoraproject.org/en/verify . I have had good luck using mirrors.kernel.org (http://mirrors.kernel.org/fedora/releases/9/Fedora/i386/iso/) but your experience may differ. These instructions will assume you have such a DVD but installing from a commercial DVD/CD set or a downloaded CD set should be essentially identical.
+
http://fedoraproject.org/wiki/Distribution/Download for information. For example you can use wxDownload Fast or BitTorrent to download an ISO image of the installation DVD and then burn your own installation DVD. If you download ISO images, make sure that you verify the integrity of the downloaded files by comparing the SHA1 checksums of the downloaded files with the SHA1 checksums listed at http://fedoraproject.org/en/verify . I have had good luck using mirrors.kernel.org (http://mirrors.kernel.org/fedora/releases/9/Fedora/i386/iso/) but your experience may differ. These instructions will assume you have burnt a DVD from <code>Fedora-9-x386_64-DVD.iso</code> but installing from a commercial DVD/CD set or a downloaded CD set should be essentially identical.
   
 
Place the installation DVD in your DVD drive and boot your computer from the DVD drive. You may have to press &lt;F12&gt; during the boot process to bring up a boot menu which will allow you to select booting from the DVD. Or you many have to edit the BIOS to select the DVD as the first boot device.
 
Place the installation DVD in your DVD drive and boot your computer from the DVD drive. You may have to press &lt;F12&gt; during the boot process to bring up a boot menu which will allow you to select booting from the DVD. Or you many have to edit the BIOS to select the DVD as the first boot device.
Line 38: Line 39:
 
# On the keyboard page select <code>U.S. English</code> and click <code>Next</code>
 
# On the keyboard page select <code>U.S. English</code> and click <code>Next</code>
 
# If you have an existing Fedora installation, you will be asked whether you want to <code>Install</code> or <code>Upgrade</code>. Select <code>Install Fedora</code> and click <code>Next</code>
 
# If you have an existing Fedora installation, you will be asked whether you want to <code>Install</code> or <code>Upgrade</code>. Select <code>Install Fedora</code> and click <code>Next</code>
# On the partitioning page you should be able to accept the defaults (unless you are dual booting operating systems, etc. but then you are not a novice user and you are on your own for that part)
 
  +
   
 
Now we configure the network. Your network interface may be set up automatically via DHCP. If this is true, you can skip the rest of this paragraph. Otherwise you will have to enter your machine's static ip address, etc. To do this
 
Now we configure the network. Your network interface may be set up automatically via DHCP. If this is true, you can skip the rest of this paragraph. Otherwise you will have to enter your machine's static ip address, etc. To do this
Line 54: Line 55:
 
# Now choose a timezone and click <code>Next</code>
 
# Now choose a timezone and click <code>Next</code>
 
# Enter the password for the root user and click <code>Next</code>. It doesn't say so, but "Do not forget what you enter here".
 
# Enter the password for the root user and click <code>Next</code>. It doesn't say so, but "Do not forget what you enter here".
  +
# On the partitioning page you should be able to accept the defaults.
   
 
On the additional tasks page uncheck <code>Office and Productivy</code>, leave the <code>additional repositories</code> space blank, leave <code>Customize now</code> unchecked and then click <code>Next</code>.
 
On the additional tasks page uncheck <code>Office and Productivy</code>, leave the <code>additional repositories</code> space blank, leave <code>Customize now</code> unchecked and then click <code>Next</code>.
Line 64: Line 66:
   
 
# Click <code>Forward</code> to continue the installation process and <code>Forward</code> again after you have read the License Information
 
# Click <code>Forward</code> to continue the installation process and <code>Forward</code> again after you have read the License Information
# Under <code>Firewall</code> check <code>Secure WWW (HTTPS)</code> and <code>WWW (HTTPS)</code>, leave <code>SSH</code> checked, click <code>Forward</code> and then click <code>Yes</code> to confirm
 
  +
# Now enter yourself as a regular user and click <code>Forward</code>
# Under <code>SELinux</code> select <code>Disabled</code>, click <code>Forward</code> and then click <code>Yes</code> to confirm
 
 
# Set the Date and Time and if you want enable the Network Time Protocol. Then click <code>Forward</code>
 
# Set the Date and Time and if you want enable the Network Time Protocol. Then click <code>Forward</code>
 
# Next I just clicked <code>Forward</code> choosing not to send my hardware profile and confirmed my choice
 
# Next I just clicked <code>Forward</code> choosing not to send my hardware profile and confirmed my choice
# Now enter yourself as a regular user and click <code>Forward</code>
 
# If you have a sound card you will be asked if you want to test it
 
# Finally click <code>Finish</code> and <code>OK</code> to reboot
 
   
 
 
 
# Log into your regular account but
 
# Log into your regular account but
 
# Before you do anything, wait several minutes to allow the system to check for Updates
 
# Before you do anything, wait several minutes to allow the system to check for Updates
# You will see a pop up window. Click <code>View updates</code>. You will have to enter the <code>&lt;root password&gt;</code>. Then after the update information is retrieved click <code>Apply updates</code> and click <code>continue</code> to accept any dependencies. Follow any instructions, e.g. you may be asked to import a key for gnome and/or if you install a new kernel, you may be told to reboot as soon as the installation is completed (to reboot, select <code>Reboot now</code> in the pop up window). Note that if you don't choose to install the updates at this time, you will see the update pop up window every time you reboot.
+
# You will see a pop up window. Click <code>Update computer now</code>. You will have to enter the <code>&lt;root password&gt;</code>. This may take awhile; the icons will give you some information on the progress of the update. Follow any instructions, e.g. you may be asked to import a key for gnome and/or if you install a new kernel, you may be told to reboot as soon as the installation is completed (to reboot, select <code>Reboot now</code> in the pop up window). Note that if you don't choose to install the updates at this time, you will see the update pop up window every time you reboot.
  +
  +
# Select <code>System</code>, <code>Administration</code>, <code>Firewall</code>. You will have to enter the <code>&lt;root password&gt;</code>. The <code>Firewall Configuration</code> window will open
  +
# Under <code>Service</code> check <code>Secure WWW (HTTPS)</code>, <code>SSH</code> and <code>WWW (HTTP)</code>. Then click <code>File</code>,<code>Apply</code> and click <code>Yes</code> to confirm. Then Quit
  +
# Select <code>System</code>, <code>Administration</code>, <code>SELinux Management</code>. The <code>SELinux Administration</code> window will open
  +
# Under <code>System Default Enforcing Mode</code> select <code>Disabled</code>,and then click <code>Yes</code> to confirm. Then Quit
  +
'''Don't skip the step of disabling SELinux or you will have a rat's nest of permission problems.'''
   
 
===Test Browser and Keyboard ===
 
===Test Browser and Keyboard ===
Line 129: Line 127:
   
 
$ sudo <command>
 
$ sudo <command>
Password: <root password>
+
Password: <your password>
   
 
After you enter the password the command is executed. For a certain period (maybe 5 minutes) you can execute additional <code>sudo</code> commands without reentering <code>&lt;your password&gt;</code>. A log of all <code>sudo</code> commands is kept (I don't know where). In these instructions for the most part we will not use <code>sudo</code>, but keep it in mind for other times that you have to become <code>root</code> in order to execute a few commands (e.g. restarting <code>apache</code>).
 
After you enter the password the command is executed. For a certain period (maybe 5 minutes) you can execute additional <code>sudo</code> commands without reentering <code>&lt;your password&gt;</code>. A log of all <code>sudo</code> commands is kept (I don't know where). In these instructions for the most part we will not use <code>sudo</code>, but keep it in mind for other times that you have to become <code>root</code> in order to execute a few commands (e.g. restarting <code>apache</code>).
Line 157: Line 155:
 
Our next task is to install a number of Fedora software packages.
 
Our next task is to install a number of Fedora software packages.
   
# Select <code>System</code>, <code>Administration</code> and then <code>Add/Remove Software</code>. You will have to enter the <code>&lt;your password&gt;</code>. The <code>Package Manager</code> window will open
+
# Select <code>System</code>, <code>Administration</code> and then <code>Add/Remove Software</code>. You may have to enter the <code>&lt;root password&gt;</code> either now or later in the process. The <code>Package Manager</code> window will open
 
# Select <code>System</code> and then click on <code>Refresh Application Lists</code> to bring the package information up to date
 
# Select <code>System</code> and then click on <code>Refresh Application Lists</code> to bring the package information up to date
   
Line 163: Line 161:
   
 
# We are searching for <code>libapreq2</code> so enter <code>libapreq2</code> (you can copy and paste from this document if you want) in the search window and click <code>Find</code>
 
# We are searching for <code>libapreq2</code> so enter <code>libapreq2</code> (you can copy and paste from this document if you want) in the search window and click <code>Find</code>
# This should result in 3 possibilities. Select <code>libapreq2</code> which will be listed as <code>libapreq2-2.09-0.15.rc2.fc9(i386)</code> or something very similar. We will just give the initial part of the package name. Then click <code>install/code>. Double clicking selects and installs in one operation. After the installation finished, you will see an open box or package symbol.
+
# This should result in 3 possibilities. Select <code>libapreq2</code> which will be listed as <code>libapreq2-2.09-0.15.rc2.fc9(i386)</code> or something very similar. We will just give the initial part of the package name. Then click <code>install</code>. Double clicking selects and installs in one operation. After the installation finished, you will see an open box or package symbol.
 
# Follow this basic procedure for all the packages listed below
 
# Follow this basic procedure for all the packages listed below
   
Here is the list of Fedora packages that need to be installed. See [[Installation Manual for 2.4]] for a short explanation of what most of these packages do.
+
Here is the list of Fedora packages that need to be installed. See [[Installation Manual for 2.4]] for a short explanation of what most of these packages do.
   
# <code>CVS</code>
+
# <code>cvs</code>
 
# <code>dvipng</code>
 
# <code>dvipng</code>
 
# <code>libapreq2</code>
 
# <code>libapreq2</code>
Line 191: Line 189:
   
 
Now close the <code><code>Add/Remove Software</code></code> window by selecting <code>System</code> <code>Quit</code>.
 
Now close the <code><code>Add/Remove Software</code></code> window by selecting <code>System</code> <code>Quit</code>.
  +
  +
Unfortunately there seems to be a bug in the Fedora 9 installation whereby necessaraay TeX formatting files are not installed. To correct this do the following
  +
  +
$ su
  +
Password: <root password>
  +
# fmtutil-sys --all
  +
# exit
  +
$
  +
When I did this there were three errors that you can ignore.
   
 
That completes the set up of your base Fedora system.
 
That completes the set up of your base Fedora system.
Line 240: Line 247:
   
 
Since this is the first time you are using CPAN it will ask you <code>Are you ready for manual configuration?</code>
 
Since this is the first time you are using CPAN it will ask you <code>Are you ready for manual configuration?</code>
Respond <code>no</code> and after that select all defaults (by hitting <code>&lt;Enter&gt;</code>) until you are forced to enter a continent and country. Then select the mirror ftp://mirrors.kernel.org/pub/CPAN (number 35 on my list). When you again see the cpan prompt enter
 
  +
Respond <code>yes</code> and that should be it.
 
cpan> reload index
 
 
Now we tell cpan the location of some important programs
 
   
cpan> o conf tar /bin/tar
 
cpan> o conf bzip2 /usr/bin/bzip2
 
cpan> o conf gzip /usr/bin/gzip
 
   
 
Note that one time this failed when I tried to do it in the evening but when I tried again the next morning it worked fine. Now we update CPAN itself
 
Note that one time this failed when I tried to do it in the evening but when I tried again the next morning it worked fine. Now we update CPAN itself
Line 344: Line 344:
 
# gedit httpd.conf
 
# gedit httpd.conf
   
First search for <code># ExtendedStatus On</code> and uncomment it, i.e. remove the <code>#</code>
+
First search for <code>#ExtendedStatus On</code> and uncomment it, i.e. remove the <code>#</code>
   
 
In the <code>gedit</code> edit window near the end of the file uncomment the operational lines below. Leave the obvious comment lines (<code># Allow server status reports ... domain to enable.</code> and <code># Allow remote server configuration reports... domain to enable.</code>) commented.
 
In the <code>gedit</code> edit window near the end of the file uncomment the operational lines below. Leave the obvious comment lines (<code># Allow server status reports ... domain to enable.</code> and <code># Allow remote server configuration reports... domain to enable.</code>) commented.
Line 418: Line 418:
 
<root password>
 
<root password>
 
# /etc/init.d/httpd graceful
 
# /etc/init.d/httpd graceful
# exit
+
#
$
+
   
 
and test your server by connecting to
 
and test your server by connecting to
Line 442: Line 442:
 
# Enter the <code>&lt;root password&gt;</code>
 
# Enter the <code>&lt;root password&gt;</code>
 
# Scroll down until you find <code>httpd</code>
 
# Scroll down until you find <code>httpd</code>
# Check the checkbox next to <code>httpd</code>; this will start Apache automatically at bootup
+
# Select the <code>httpd</code> line and click <code>Enable</code>; this will start Apache automatically at bootup
# Click <code>Save</code>
+
# The http service should start and you will see a green dot.
# Close the <code>Service Configuration</code> window
+
# Then <code>Quit</code>
   
You can also use this <code>Service Configuration</code> window to stop, start, or restart Apache
+
You can also use this <code>Service Configuration</code> window to stop, start, or restart Apache but I have found this difficult to use.
 
 
Now we edit httpd.conf one more time. By default a ton of modules are loaded many which we don't require. We will comment out the ones we don't need
+
Now we edit httpd.conf one more time.
  +
gedit httpd.conf
  +
By default a ton of modules are loaded many which we don't require. We will comment out the ones we don't need
   
 
These modules are loaded by default
 
These modules are loaded by default
Line 504: Line 504:
 
LoadModule cgi_module modules/mod_cgi.so
 
LoadModule cgi_module modules/mod_cgi.so
   
Edited Loadmodule list
+
Replace this list by the following Loadmodule list
   
 
LoadModule auth_basic_module modules/mod_auth_basic.so
 
LoadModule auth_basic_module modules/mod_auth_basic.so
Line 557: Line 557:
 
# LoadModule mem_cache_module modules/mod_mem_cache.so
 
# LoadModule mem_cache_module modules/mod_mem_cache.so
 
LoadModule cgi_module modules/mod_cgi.so
 
LoadModule cgi_module modules/mod_cgi.so
  +
  +
Then save the file and quit (<code>Save</code> and <code>File</code>, <code>Quit</code>) and restart Apache
  +
# /etc/init.d/httpd graceful
  +
# exit
  +
$
   
 
== Configuring MySQL ==
 
== Configuring MySQL ==
Line 576: Line 581:
 
# The MySQL service should start and you will see a green dot.
 
# The MySQL service should start and you will see a green dot.
 
# Quit the <code>Service Configuration</code> window
 
# Quit the <code>Service Configuration</code> window
 
You can quickly check that MySQL is running by
 
 
$ mysql -u root
 
 
You should see
 
 
Welcome to the MySQL monitor. Commands end with ; or \g.
 
Your MySQL connection id is 2
 
Server version: 5.0.51a Source distribution
 
 
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
 
 
mysql>
 
 
Enter <code>exit</code> to exit
 
 
mysql> exit
 
Bye
 
$
 
   
 
== Reboot and Test ==
 
== Reboot and Test ==
Line 610: Line 595:
   
 
$ mysql -u root
 
$ mysql -u root
...
 
  +
Welcome to the MySQL monitor. Commands end with ; or \g.
  +
Your MySQL connection id is 2
  +
Server version: 5.0.51a Source distribution
  +
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
 
mysql>
 
mysql>
  +
  +
Now type <code>exit</code> to quit
  +
 
mysql> exit
 
mysql> exit
 
Bye
 
Bye
Line 618: Line 609:
 
Currently the MySQL password is empty so we didn't need a password.
 
Currently the MySQL password is empty so we didn't need a password.
 
We will take care of that now.
 
We will take care of that now.
 
 
   
 
== MySQL Security Issuses ==
 
== MySQL Security Issuses ==
Line 637: Line 626:
 
# /usr/bin/mysql_secure_installation
 
# /usr/bin/mysql_secure_installation
   
The current MYSQL root password is empty so just hit <code>&lt;Enter&gt;</code> for the password. Now answer Yes (<code>Y</code>) to all prompts. When prompted enter your choosen MySQL <code>root</code> password. As was said above, "Do not forget what you enter here". Also remember that this is the password for the MySQL <code>root</code> user, not the Fedora linux system <code>root</code> user. Below we refer to this as <code>&lt;mysql root password&gt;</code>. Now become a regular user and start MSQL again using the <code>&lt;mysql root password&gt;</code>.
+
The current MYSQL root password is empty so just hit <code>&lt;Enter&gt;</code> for the password. Now answer Yes (<code>Y</code>) to all prompts. When prompted enter your choosen MySQL <code>root</code> password. As was said above, "Do not forget what you enter here". Also remember that this is the password for the MySQL <code>root</code> user, not the Fedora linux system <code>root</code> user. Below we refer to this as <code>&lt;mysql root password&gt;</code>.
   
# exit
 
  +
Finally we secure the MySQL server by disallowing access via TCP/IP. To do this we have to edit the MySQL configuration file <code>my.cnf</code> .
$ mysql -u root -p
 
Enter Password: <mysql root password>
 
   
mysql> SELECT Host, User, Password FROM mysql.user;
 
   
and you should see that the two <code>root</code> users now have (encrypted) passwords.
 
 
Then exit MySQL
 
 
mysql> exit
 
Bye
 
$
 
 
 
and test that all is well:
 
 
$ mysql -u root -p
 
Enter Password: <mysql root password>
 
 
You should see
 
 
Welcome to the MySQL monitor ...
 
mysql>
 
 
Enter
 
 
mysql> SELECT Host, User, Password FROM mysql.user;
 
 
and you should see encrypted passwords for one root account on localhost. Now exit MySQL
 
 
mysql> exit
 
Bye
 
$
 
 
 
Finally we secure the MySQL server by disallowing access via TCP/IP. To do this we have to edit the MySQL configuration file <code>my.cnf</code> .
 
 
$su
 
<root password>
 
 
# cd /etc
 
# cd /etc
 
# cp my.cnf my.cnf.bak1
 
# cp my.cnf my.cnf.bak1
Line 716: Line 668:
 
$ cd downloads
 
$ cd downloads
 
 
$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout -r rel-2-4-dev webwork2 pg
+
$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout -r rel-2-4-patches webwork2 pg
$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/asu checkout database_problems
+
$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/npl checkout NationalProblemLibrary
   
The first download gives you the latest released version with patches (don't be misled by the <code>dev</code> extension --- this is not a development version).
+
The first download gives you the latest released version with patches. The second download contains the WeBWorK National Problem Library. This now includes the Rochester and Union Libraries along with others as sub libraries. Your system will be loaded with many thousands of WeBWorK problems (over 16,000 currently).
The second download contains the WeBWorK National Problem Library. This now includes the Rochester and Union Libraries along with others as sunlibraries. There is quite a bit of overlap between these libraries but now you system is loaded with many thousands of WeBWorK problems (over 13,000 in the National Problem Library main collection alone).
 
   
 
== Installing WeBWorK ==
 
== Installing WeBWorK ==
Line 735: Line 687:
 
# mkdir /opt/webwork/courses
 
# mkdir /opt/webwork/courses
 
# mkdir /opt/webwork/libraries
 
# mkdir /opt/webwork/libraries
# mv database_problems/ /opt/webwork/libraries/
+
# mv NationalProblemLibrary /opt/webwork/libraries/
 
# cd /opt/webwork/webwork2/courses.dist
 
# cd /opt/webwork/webwork2/courses.dist
 
# cp *.lst /opt/webwork/courses/
 
# cp *.lst /opt/webwork/courses/
Line 853: Line 805:
 
At this point <code>TtH</code> is a deprecated display mode which we didn't install so we have to remove it from the listof possible display modes.
 
At this point <code>TtH</code> is a deprecated display mode which we didn't install so we have to remove it from the listof possible display modes.
   
# Search for <code>formattedText</code> and comment out the line = "formattedText", # format math expressions using TtH=
+
# Search for <code>formattedText</code> and comment out the line <code> "formattedText", # format math expressions using TtH</code>
 
so it becomes
 
so it becomes
   
 
# "formattedText", # format math expressions using TtH
 
# "formattedText", # format math expressions using TtH
   
We need to set a password that WeBWorK uses when it communicates with the MySQL database.
+
We need to set a password that WeBWorK uses when it communicates with the MySQL database. Note that this is not the same as the <code>&lt;mysql root password&gt;</code> which is the password the MySQL root user uses.
 
# Search for <code>$database_password = "";</code> and replace this by <br /> <code>$database_password = "database_password";</code>
 
# Search for <code>$database_password = "";</code> and replace this by <br /> <code>$database_password = "database_password";</code>
 
where of course you should replace 'database_password' with your own password. Remember this password as we will need it below.
 
where of course you should replace 'database_password' with your own password. Remember this password as we will need it below.
Line 927: Line 879:
 
# cd /etc/httpd/conf.d
 
# cd /etc/httpd/conf.d
 
# ln -s /opt/webwork/webwork2/conf/webwork.apache2-config webwork.conf
 
# ln -s /opt/webwork/webwork2/conf/webwork.apache2-config webwork.conf
  +
  +
Next we will make a few changes to Apache's default configuration.
  +
# cd /etc/httpd/conf
  +
# gedit httpd.conf
  +
  +
Search for the line
  +
Timeout 120
  +
and replace it by
  +
Timeout 1200
  +
Next seach for the lines
  +
MaxClients 256
  +
MaxRequestsPerChild 4000
  +
Which occur under <code><IfModule prefork.c</code> and replace them by
  +
# For WeBWorK a rough rule of thumb is 20 MaxClients per 1 GB of memory
  +
MaxClients 20
  +
MaxRequestsPerChild 100
  +
where you should set <code>MaxClients</code> depending on the amount of memory your server has.
  +
  +
Then save the file and quit.
   
 
Then restart Apache
 
Then restart Apache
Line 945: Line 916:
 
# exit
 
# exit
 
$
 
$
$ cd /etc/apache2/
+
$ cd /etc/httpd/conf
$ diff apache2.conf apache2.conf.bak1
+
$ diff httpd.conf httpd.conf.bak1
 
$ cd /opt/webwork/webwork2/conf/
 
$ cd /opt/webwork/webwork2/conf/
 
$ diff global.conf global.conf.dist
 
$ diff global.conf global.conf.dist
Line 988: Line 959:
 
# Enter the password, check <code>Save changes</code> and then click <code>Take Action!</code>
 
# Enter the password, check <code>Save changes</code> and then click <code>Take Action!</code>
 
# Finally give yourself <code>professor</code> privilges by selecting yourself with a check mark, checking <code>Edit Selected users</code> and then clicking <code>Take Action!</code> (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)
 
# Finally give yourself <code>professor</code> privilges by selecting yourself with a check mark, checking <code>Edit Selected users</code> and then clicking <code>Take Action!</code> (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)
# Now at the far right change <code>Permission Level</code> from 0 (an ordinary student) to 10 (an esteemed professor)
+
# Now at the far right change <code>Permission Level</code> from <code>student</code> to <code>professor</code>
 
# Check <code>Save changes</code> and then click <code>Take Action!</code>
 
# Check <code>Save changes</code> and then click <code>Take Action!</code>
   
Line 994: Line 965:
 
To hide a course place a file named <code>hide_directory</code> in the course directory and it 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>http://yourserver.yourschool.edu/webwork2/admin</code> but you will not see a link for it on the WeBWorK home page <code>http://yourserver.yourschool.edu/webwork2</code> . Let's hide the <code>admin</code> course.
 
To hide a course place a file named <code>hide_directory</code> in the course directory and it 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>http://yourserver.yourschool.edu/webwork2/admin</code> but you will not see a link for it on the WeBWorK home page <code>http://yourserver.yourschool.edu/webwork2</code> . Let's hide the <code>admin</code> course.
   
$ cd
 
  +
$ sudo cp /opt/webwork/courses/modelCourse/hide_directory /opt/webwork/courses/admin
$ gedit hide_directory
 
 
Now you don't really have to put any verbiage in the file but I suggest you put:
 
 
Place a file named "hide_directory" in a course or other directory
 
and it will not show up in the courses list on the WeBWorK home page.
 
It will still appear in the Course Administration listing.
 
 
Save the file and quit. Now copy the file to the <code>admin</code> course.
 
 
$ sudo cp hide_directory /opt/webwork/courses/admin
 
 
password:<your password>
 
password:<your password>
   
Now goto <code>http://yourserver.yourschool.edu/webwork2</code> and no course will be listed.
+
Now goto <code>http://yourserver.yourschool.edu/webwork2</code> and no course will be listed.
   
 
== Starting and Stoping Apache, MySQL and the GNOME desktop GUI ==
 
== Starting and Stoping Apache, MySQL and the GNOME desktop GUI ==
Line 1,063: Line 1,023:
 
The GNOME desktop is automatically started when the system boots.
 
The GNOME desktop is automatically started when the system boots.
   
%RED% NOTE: The following instructions work in Debian but not in Fedora 7. I haven't found an easy way to stop and start the GNOME desktop GUI in Fedora 7. %ENDCOLOR%
+
%RED% NOTE: The following instructions work in Debian but not in Fedora 7. I haven't found an easy way to stop and start the GNOME desktop GUI in Fedora. %ENDCOLOR%
   
 
To stop <code>GNOME</code> so that you only have a standard terminal window run the following in a standard terminal window
 
To stop <code>GNOME</code> so that you only have a standard terminal window run the following in a standard terminal window
Line 1,079: Line 1,039:
   
 
===Install the National Problem Library ===
 
===Install the National Problem Library ===
The <code>National Problem Library</code> consists of both WeBWorK problems and methods for searching and selecting problems. Also it contains as sub libraries many of the other standard libraries. Normally this library is referred to as the <code>ProblemLibrary</code> but the downloaded CVS directory for it is named <code>database_problems</code>. So the first thing we do is to link <code>ProblemLibrary</code> to <code>database_problems</code>.
+
The <code>National Problem Library</code> 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 tell WeBWork where to find it.
   
$ cd /opt/webwork/libraries/
 
  +
Edit <code>global.conf</code>.
$ sudo ln -s database_problems ProblemLibrary
 
password:<your password>
 
 
Next we have to edit <code>global.conf</code>.
 
   
 
$ cd /opt/webwork/webwork2/conf
 
$ cd /opt/webwork/webwork2/conf
Line 1,092: Line 1,048:
 
# gedit global.conf
 
# gedit global.conf
   
# Search for <code>problemLibrary</code> and replace <code>$problemLibrary{root} = "";</code> by <br /> <code>$problemLibrary{root} = "/opt/webwork/libraries/ProblemLibrary";</code>
+
Search for <code>problemLibrary</code> and replace <code>$problemLibrary{root} = "";</code> by <br /> <code>$problemLibrary{root} = "/opt/webwork/libraries/NationalProblemLibrary";</code>
   
 
Then save the file and quit. And return to a regular user
 
Then save the file and quit. And return to a regular user
Line 1,099: Line 1,055:
 
$
 
$
   
We now create a database, called <code>ProblemLibrary</code>, for for the Problem Library.
 
  +
Run the <code>NPL-update</code> script making sure you are in the <code>/opt/webwork/libraries/NationalProblemLibrary</code> directory. This directory contains the files <code>loadDB2</code> and <code>create_tables2.sql</code>.
To do this do the following:
 
 
$ mysql -u root -p mysql
 
Enter password: &lt;mysql root password&gt;
 
mysql> CREATE DATABASE ProblemLibrary;
 
mysql> GRANT SELECT ON ProblemLibrary.* TO webworkWrite@localhost;
 
mysql> exit
 
Bye
 
$
 
 
Run the installation script making sure you are in the <code>/opt/webwork/libraries/ProblemLibrary</code> directory. This directory
 
contains the files <code>loadDB2</code> and <code>create_tables2.sql</code>.
 
   
 
$ cd /opt/webwork/libraries/ProblemLibrary
 
$ cd /opt/webwork/libraries/ProblemLibrary
 
$ NPL-update
 
$ NPL-update
   
This has to convert a lot of data so please be patient; it can take a long time.
+
This has to convert a lot of data (around 16900 files) so please be patient; it can take a long time.
   
 
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
Line 1,137: Line 1,081:
 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code>unionLibrary =&gt; "Union",</code>
 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code>unionLibrary =&gt; "Union",</code>
 
# Search for <code>macrosPath</code> and scroll down several lines to the line <br /> <code>$pg{directories}{macros},</code>
 
# Search for <code>macrosPath</code> and scroll down several lines to the line <br /> <code>$pg{directories}{macros},</code>
# After this line add the line: <br /> <code>'/opt/webwork/libraries/database_problems/macros/Union',</code>
+
# After this line add the line: <br /> <code>'/opt/webwork/libraries/NationalProblemLibrary/macros/Union',</code>
   
 
Don't forget the coma (<code>,</code>) at the end of these lines. Then save the file and quit.
 
Don't forget the coma (<code>,</code>) at the end of these lines. Then save the file and quit.
Line 1,152: Line 1,096:
   
 
$ cd /opt/webwork/courses/modelCourse/templates/
 
$ cd /opt/webwork/courses/modelCourse/templates/
$ sudo ln -s /opt/webwork/libraries/database_problems/Union unionLibrary
+
$ sudo ln -s /opt/webwork/libraries/NationalProblemLibrary/Union unionLibrary
 
password: <your password>
 
password: <your password>
$ sudo ln -s /opt/webwork/libraries/database_problems/Rochester rochesterLibrary
+
$ sudo ln -s /opt/webwork/libraries/NationalProblemLibrary/Rochester rochesterLibrary
   
 
If you want to put another library into the <code>modelCourse</code>, just do the analogous thing. If you just want the additional library in a particular course, add the link in the <code>templates</code> directory of that course. If you look in the directory <code>/opt/webwork/libraries/database_problems/</code> you might find other libraries that are not yet listed in <code>global.conf</code> (like <code>Union</code> above) and these can be added in the same way we added <code>Union</code>. Usually they do not require additional macros like <code>Union</code> did. Finally if you add a library with non standard symbols in the name (e.g. <code>uva-statLibrary</code>) you have to use single quotes when adding it to <code>global.conf</code>, e.g. <br>
 
If you want to put another library into the <code>modelCourse</code>, just do the analogous thing. If you just want the additional library in a particular course, add the link in the <code>templates</code> directory of that course. If you look in the directory <code>/opt/webwork/libraries/database_problems/</code> you might find other libraries that are not yet listed in <code>global.conf</code> (like <code>Union</code> above) and these can be added in the same way we added <code>Union</code>. Usually they do not require additional macros like <code>Union</code> did. Finally if you add a library with non standard symbols in the name (e.g. <code>uva-statLibrary</code>) you have to use single quotes when adding it to <code>global.conf</code>, e.g. <br>
Line 1,177: Line 1,121:
   
 
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.
  +
  +
==Test that Things are Working Properly ==
  +
  +
We will test out a few important parts of WeBWorK. If you run into problems, you should look at the Apache error log which is located at <code>/etc/httpd/logs/error.log</code>.
  +
  +
Click on <code>Hmwk Sets Editor</code> on the <code>Main Menu</code>. Then select (by clicking the circle button) <code>Import</code>, select <code>setDemo.def</code> from the <code>from</code> drop down list and select <code>all current users</code> from the <code>assigning this set to</code> drop down list. Then hit <code>Take Action!</code>
  +
  +
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. Then look at the problems. Mathematical equations should be typeset. If not, edit the file <code>Constants.pm</code> in the directory <code>/opt/webwork/webwork2/lib/WeBWorK</code>. Change the line <code>$WeBWorK::PG::ImageGenerator::PreserveTempFiles = 0;</code> to <code>...::PreserveTempFiles = 1;</code>. Then restart Apache and view the first couple problems or some new ones. Then look in the directory <code>/opt/webwork/webwork2/tmp/</code>. <code>cd</code> to one of the <code>ImageGenerator.../tmp/</code> directories and look at the error and log files there. When you fix the problem remember to edit <code>...::PreserveTempFiles = 1;</code> back to 0 and restart Apache or you will be saving a lot of unnecessary files. Another useful trick is to try downloading a hard copy of an assignment and then (assuming there are errors) looking at the various log files that are linked to on the output page.
  +
  +
When you continue looking at problems you will get an error when you try to look at Problem 6 because we have not configured the CAPA macros which are required to display CAPA problems. Unless you are teaching physics you probably don't need them. Also in Problem 9 the Java applet will not load. Problem 9 was written in the 90's and used an applet on a server at The Johns Hopkins University. The server went away a long time ago but have retained this problem for historical reasons and also because it is a example of several things (e.g. WeBWorK problems can include applets running on remote servers but this can lead to other problems).
  +
  +
Next click on <code>Prob. List</code> to bring back the Problem List Page and click on <code>Download a hardcopy of this homework set</code>. The page is a little complicated because you are a professor but you can just scroll to the bottom and click on <code>Generate hardcopy for selected users and selected sets</code>. You will get an error (because of the bad Problem 6) but just click <code>Download Hardcopy</code> to get what was generated. Also you can see links to various
  +
informational files that are available if you run into problems (normally these files are removed if there are no errors).
  +
  +
Another thing to do is to use <code>Email</code> on the <code>Main Menu</code>. Again this page is a little complicated because you can do a lot of things with it (including mail merge) but at this point just select yourself in the list to the right and hit <code>Send Email</code> at the bottom. You should receive two emails. One is the message you just sent and the other is an email with subject "WeBWorK email sent" giving information on your mailing.
  +
  +
As a final test click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Problem Library </code>
  +
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed. You can also test that you can access any additional Problem Libraries that you installed.
  +
  +
If all the above tests work, you can be pretty confident that WeBWorK is working properly.
  +
  +
Go back to <code>Hmwk Sets Editor</code> on the <code>Main Menu</code>. Then select (by clicking the circle button) <code>Import</code>, select <code>setOrientation.def</code> from the <code>from</code> drop down list and select <code>all current users</code> from the <code>assigning this set to</code> drop down list. Then hit <code>Take Action!</code>. Then go through the Orientation problems. This is a good first set to use for introducing students to WeBWorK.
  +
  +
If you are new to WeBWorK, you should probably add a regular student to myTestCourse and log in as that student to see what the student interface looks like. It's much simpler than the professor interface.
  +
Click on <code>Classlist Editor</code> on the <code>Main Menu</code>.
  +
Then select (by clicking the circle button) <code>Add 1 student(s)</code>and hit <code>Take Action!</code>. Add one student, say Jane Smith, with <code>Student ID</code> <code>1234</code> and <code>Login Name</code> <code>jsmith</code>.
  +
Jane Smith's initial password will be her <code>Student ID</code> <code>1234</code>. Now login as Jane Smith and play around a little.
   
 
==Where to go From Here ==
 
==Where to go From Here ==

Latest revision as of 16:14, 3 June 2013

This article has been retained as a historical document. It is not up-to-date and the formatting may be lacking. Use the information herein with caution.
This deprecated feature should no longer be used, but is still available for reasons of backwards compatibility.

This feature was deprecated in version 2.6. For up-to-date information view Github. 9


See also: History of WeBWorK version control


These instructions cover the installation of the Fedora Linux 9 operating system and WeBWorK 2.4 from scratch.

They are more detailed (but offer fewer choices and often less background information) than the general Installation Manual for 2.4 and are aimed at non unix experts. Readers may want to quickly scan Installation Manual for 2.4 to get an overview of the installation process and then carefully read and follow these instructions.

Notation

First some short comments on notation we will be using. We will use <key> to indicate that you should press a specific key (e.g. <Enter>, <Tab>, <F6>, etc.). Sometimes we will also use e.g. <root password> to indicate you have to enter the root password.

^ will indicate the <Ctrl> key so e.g. ^X is really shorthand for <Ctrl> <X>, i.e. press the Ctrl key and hit the X key.

We will give references to specific versions of software, e.g. uuid-perl - 1.5.1-2.fc7.i386 rather than the more general uuid-perl - xxx.i386 . In most cases you should be able to use the latest stable version but we have only tested the versions listed.

Installing the Fedora 9 Linux Operating System

Installation DVD

Obtain the installation DVD/CD set. Connect to http://fedoraproject.org/wiki/Distribution/Download for information. For example you can use wxDownload Fast or BitTorrent to download an ISO image of the installation DVD and then burn your own installation DVD. If you download ISO images, make sure that you verify the integrity of the downloaded files by comparing the SHA1 checksums of the downloaded files with the SHA1 checksums listed at http://fedoraproject.org/en/verify . I have had good luck using mirrors.kernel.org (http://mirrors.kernel.org/fedora/releases/9/Fedora/i386/iso/) but your experience may differ. These instructions will assume you have burnt a DVD from Fedora-9-x386_64-DVD.iso but installing from a commercial DVD/CD set or a downloaded CD set should be essentially identical.

Place the installation DVD in your DVD drive and boot your computer from the DVD drive. You may have to press <F12> during the boot process to bring up a boot menu which will allow you to select booting from the DVD. Or you many have to edit the BIOS to select the DVD as the first boot device.

You will see a list of options.

  1. Hit <Enter> to select Install or upgrade an existing system
  2. If you checked the SHA1 checksum you can probably Skip the media test as it is quite a time consuming process. If you have doubts run the test
  3. Click Next to continue unless you want to read the Release Notes
  4. On the language page select English(US) and click Next
  5. On the keyboard page select U.S. English and click Next
  6. If you have an existing Fedora installation, you will be asked whether you want to Install or Upgrade. Select Install Fedora and click Next


Now we configure the network. Your network interface may be set up automatically via DHCP. If this is true, you can skip the rest of this paragraph. Otherwise you will have to enter your machine's static ip address, etc. To do this

  1. Click Edit
  2. Under Enable Ipv4 support check manual configuration (which will deselect Use dynamic IP configuration (DHCP))
  3. Enter the IP Address under Address in the IPv4 line
  4. For the Prefix (Netmask) you probably want to enter 255.255.255.0 but another possibility may be 255.255.0.0
  5. Unless your school is employing the IPv6 protocol, remove the checkmark from Enable IPv6 support
  6. Then click OK
  7. Under Hostname check manually and enter your hostname, e.g. yourserver.yourdepartment.yourschool.edu
  8. Under Miscellaneous Settings enter the ip address of your Gateway and the ip addresses of your nameserver(s). At a minimum you have to enter the ip address of the Primary DNS
  9. Then click Next

Now we continue with the installation

  1. Now choose a timezone and click Next
  2. Enter the password for the root user and click Next. It doesn't say so, but "Do not forget what you enter here".
  3. On the partitioning page you should be able to accept the defaults.

On the additional tasks page uncheck Office and Productivy, leave the additional repositories space blank, leave Customize now unchecked and then click Next.

  1. Click Next to begin installing Fedora.
  2. Sit back and relax while the installation takes place --- this may take awhile

Continue Installation

After this finishes the system will eject the DVD and ask you to reboot. Click Reboot.

  1. Click Forward to continue the installation process and Forward again after you have read the License Information
  2. Now enter yourself as a regular user and click Forward
  3. Set the Date and Time and if you want enable the Network Time Protocol. Then click Forward
  4. Next I just clicked Forward choosing not to send my hardware profile and confirmed my choice


  1. Log into your regular account but
  2. Before you do anything, wait several minutes to allow the system to check for Updates
  3. You will see a pop up window. Click Update computer now. You will have to enter the <root password>. This may take awhile; the icons will give you some information on the progress of the update. Follow any instructions, e.g. you may be asked to import a key for gnome and/or if you install a new kernel, you may be told to reboot as soon as the installation is completed (to reboot, select Reboot now in the pop up window). Note that if you don't choose to install the updates at this time, you will see the update pop up window every time you reboot.
  1. Select System, Administration, Firewall. You will have to enter the <root password>. The Firewall Configuration window will open
  2. Under Service check Secure WWW (HTTPS), SSH and WWW (HTTP). Then click File,Apply and click Yes to confirm. Then Quit
  3. Select System, Administration, SELinux Management. The SELinux Administration window will open
  4. Under System Default Enforcing Mode select Disabled,and then click Yes to confirm. Then Quit

Don't skip the step of disabling SELinux or you will have a rat's nest of permission problems.

Test Browser and Keyboard

After reboot and login, click on Applications, Internet, Firefox Web Browser and you should be connected to the world. Goto [[1]] where you can view this document and, if you want, copy commands that you need (see below).

Here's an aside on keystroke delay and repetition rate. If you are like me and find the keystroke delay too short (so that you often type "geeet" when you want to type "get"), do the following. Click System, Preferences, Hardware, Keyboard and then increase the delay time interval and hit Close.

Terminal Window Notation and Use

Before installing and configuring additional software, we need to talk about terminal windows.

To open a terminal window click Applications, System Tools and then select Terminal.

In a terminal window some commands will have to be run as root whereas others should be run as a regular user. We will use # to indicate that the command is to be run as root e.g.

# perl -MCPAN -e shell

and $ to indicate that the command is to be run as a normal user e.g.

$ cp .bashrc .bashrc.bak1

To execute the above commands you have to hit <Enter>. We'll just assume this. After executing a command, often the system will respond with text (sometimes a lot of text!) which we will usually not repeat below. We only give the commands that you should execute.

The bash shell which you will be using has a number of very convenient features.

One is command and file name completion. If you are typing (e.g. ch) and hit <tab> bash will complete the command or filename if it is unambiguous (or more precisely it will complete as much as possible). If there are multiple possibilities (as in the case of ch) nothing will happen (except you may hear a beep) and you can type more letter(s) and hit <tab> again. Or you can hit <tab> a second time and you will see a list of all possible completions. E.g. entering ch<tab><tab> gives a list of possible completions and ch<tab>g<tab> (or chg<tab>) gives chgrp, the change group command. This is very fast and convenient and it also leads to fewer typing errors.

Another useful shortcut is the command history. Using the up and down arrow keys will bring up previous commands which can be edited and then executed. If you are repeating a command or entering a command which is similar to a previous one, this is very useful.

You can copy commands from these instructions (with copy from the Edit dropdown list or ^C) and paste them into a terminal window (with paste from the Edit dropdown list or <Shift> <Ctrl> <V>). However typing yourself using command completion is probably just as fast except if a command is long.

Finally perhaps a safer way to run commands as root is to use the sudo command

$ sudo <command>
Password: <your password>

After you enter the password the command is executed. For a certain period (maybe 5 minutes) you can execute additional sudo commands without reentering <your password>. A log of all sudo commands is kept (I don't know where). In these instructions for the most part we will not use sudo, but keep it in mind for other times that you have to become root in order to execute a few commands (e.g. restarting apache). Note that in order to use sudo, you must be listed in the sudoers file. To do this become root

$ su
Password: <root password>

and then

# chmod +w /etc/sudoers
# echo 'your_user_name ALL=(ALL) ALL' >> /etc/sudoers
# chmod -w /etc/sudoers

where of course you replace your_user_name with your user name (you do need the two single quotes).

For our next terminal window task create a downloads directory where we will keep copies of downloaded software. We want to do this as a regular user so first we exit the root account.

# exit
$ cd
$ mkdir downloads

Fedora Software Packages

Our next task is to install a number of Fedora software packages.

  1. Select System, Administration and then Add/Remove Software. You may have to enter the <root password> either now or later in the process. The Package Manager window will open
  2. Select System and then click on Refresh Application Lists to bring the package information up to date

Now we will actually select and install a large number of packages. The process is the same for all packages. I'll give an example of installing libapreq2 and then just give the list of required packages.

  1. We are searching for libapreq2 so enter libapreq2 (you can copy and paste from this document if you want) in the search window and click Find
  2. This should result in 3 possibilities. Select libapreq2 which will be listed as libapreq2-2.09-0.15.rc2.fc9(i386) or something very similar. We will just give the initial part of the package name. Then click install. Double clicking selects and installs in one operation. After the installation finished, you will see an open box or package symbol.
  3. Follow this basic procedure for all the packages listed below

Here is the list of Fedora packages that need to be installed. See Installation Manual for 2.4 for a short explanation of what most of these packages do.

  1. cvs
  2. dvipng
  3. libapreq2
  4. make
  5. mod_perl
  6. mysql-server
  7. perl-CPAN
  8. perl-DateTime
  9. perl-Digest-SHA
  10. perl-Email-Address
  11. perl-GD
  12. perl-LDAP
  13. perl-libapreq2
  14. perl-Mail-Sender
  15. perl-SQL-Abstract
  16. perl-String-ShellQuote
  17. perl-TimeDate
  18. perl-XML-Parser
  19. perl-XML-Writer
  20. tex-preview
  21. uuid-perl

Now close the Add/Remove Software window by selecting System Quit.

Unfortunately there seems to be a bug in the Fedora 9 installation whereby necessaraay TeX formatting files are not installed. To correct this do the following

$ su
Password: <root password>
# fmtutil-sys --all
# exit
$

When I did this there were three errors that you can ignore.

That completes the set up of your base Fedora system.

Installing Perl Modules

We now have to install several additional Perl modules which unfortunately are not available from the Fedora package system.

Testing Perl Modules

To test if a Perl module is installed and working on your system, issue the following command in a terminal window, replacing Module with the name of the module:

$ perl -MModule -e 'print "installed!\n"'

If the module is installed you will see installed!. If not you will see at lot of gibberish. E.g. at this stage in our installation process CPAN is installed and MXML::Parser::EasyTree is not so

$ perl -MCPAN -e 'print "installed!\n"'

yields

installed!

and

$ perl -MXML::Parser::EasyTree -e 'print "installed!\n"'

yields

Can't locate XML/Parser/EasyTree.pm in @INC (@INC contains: 
/etc/perl /usr/local/lib/perl/5.8.8 /usr/local/share/perl/5.8.8
...

Installing Additional Perl Modules from CPAN

Be aware that in rare cases you might have to as root run

$ su
<root password>
# unset LANG
# exit
$

since otherwise the installation of some modules (Module::Build is an example) may fail.

First we will set up CPAN. For this you have to be root.

$ su
<root password>
# perl -MCPAN -e shell

Since this is the first time you are using CPAN it will ask you Are you ready for manual configuration? Respond yes and that should be it.


Note that one time this failed when I tried to do it in the evening but when I tried again the next morning it worked fine. Now we update CPAN itself

cpan> install Bundle::CPAN

and always hit <Enter> to accept the defaults when prompted. This can be a long process with many long pauses. Please be patient. When you again see the

cpan>

prompt enter

cpan> reload cpan
cpan> o conf commit

Now install the following modules

cpan> install XML::Parser::EasyTree Iterator Iterator::Util Net::IP 

and in case you are prompted accept all defaults by just hitting <Enter>. Note that with more than one module to install, we just list them after install separated by spaces.

When you again see the

cpan>

prompt enter

cpan> exit
#

Installing Additional Perl Modules from Source

At one point in time (August 2006), the installation of DateTime using CPAN was broken. Currently DateTime can be installed using CPAN. However it is useful to show you how to install perl modules from source in case one of the perl modules we installed above gets updated and its installation from CPAN becomes broken. If that happens you can follow the procedures outlined here to install the module from source.

IMPORTANT: With Fedora we have already installed DateTime so you don't have to install it as outlined below. We are just using this as an example of installing a module from source which hopefully you will never have to do. You can skip this section and go directly to the Apache 2 and mod_perl section.

Now we give the example of installing DateTime from source. As we said you can skip this part.

Goto [[2]], search for DateTime and click on DateTime. Then near the top right download DateTime-0.36.tar.gz and save it to disk. Move it to your downloads directory. Then

$ cd 
$ cd downloads
$ tar -zvxf DateTime-0.36.tar.gz
$ cd DateTime-0.36/


$ perl Makefile.PL
$ make
$ make test

If make test indicates something is missing you will have to install that. In fact in the case of DateTime, you would see that quite a few things are missing.

DateTime requires the additional modules version , Module::Build , Class::Singleton , DateTime::TimeZone and DateTime::Locale . We could install these using CPAN
# perl -MCPAN -e shell
cpan> install version Module::Build Class::Singleton DateTime::TimeZone DateTime::Locale
cpan> exit
# exit
$

If you see anything that looks suspicious during this process, you can always test to see if the perl module in question was in fact installed. If it was not installed try CPAN first and if CPAN fails then install it from source. The great thing about CPAN (if it works) is that it will trace down and automatically install all required components. Note that if you get a message indicating that package/file.pm was not found, you should search for and install package::file since perl modules use a double colon (::) as a directory separator.

Assuming all is OK

$su
<root password>
# make install
# exit
$

Finally you should definitely test that the module (e.g. DateTime) was installed sucessfully

$ perl -MDateTime -e 'print "installed!\n"'

If you see

installed!

you can celebrate.

Apache 2 and mod_perl

Next we make a copy of the apache configuration file for safekeeping.

$su
<root password>  
# cd /etc/httpd/conf
# cp httpd.conf httpd.conf.bak1

Next we will edit the apache configuration file httpd.conf to allow us to view information about the setup and performance of the web server. Note that this is not absolutely necessary but it can be very useful. You can use your favorite editor but we will give instructions assuming you are using gedit. Note that you have to be root to edit httpd.conf.

# gedit httpd.conf

First search for #ExtendedStatus On and uncomment it, i.e. remove the #

In the gedit edit window near the end of the file uncomment the operational lines below. Leave the obvious comment lines (# Allow server status reports ... domain to enable. and # Allow remote server configuration reports... domain to enable.) commented.

The original lines are

#
# Allow server status reports generated by mod_status,
# with the URL of http://servername/server-status
# Change the ".example.com" to match your domain to enable.
#
#<Location /server-status>
#    SetHandler server-status
#    Order deny,allow
#    Deny from all
#    Allow from .example.com
#</Location>

#
# Allow remote server configuration reports, with the URL of
#  http://servername/server-info (requires that mod_info.c be loaded).
# Change the ".example.com" to match your domain to enable.
#
#<Location /server-info>
#    SetHandler server-info
#    Order deny,allow
#    Deny from all
#    Allow from .example.com
#</Location>

Now in both places replace Allow from .example.com by Allow from 127.0.0.1. If in addition you want to allow access to server information from e.g. your department domain, add new lines Allow from .math.yourschool.edu below the two Allow from lines where of course you should edit .math.yourschool.edu appropriately. The code (except for yourschool) should look like

#
# Allow server status reports generated by mod_status,
# with the URL of http://servername/server-status
# Change the ".example.com" to match your domain to enable.
#
<Location /server-status>
    SetHandler server-status
    Order deny,allow
    Deny from all
    Allow from 127.0.0.1
    Allow from .math.yourschool.edu
</Location>

#
# Allow remote server configuration reports, with the URL of
#  http://servername/server-info (requires that mod_info.c be loaded).
# Change the ".example.com" to match your domain to enable.
#
<Location /server-info>
    SetHandler server-info
    Order deny,allow
    Deny from all
    Allow from 127.0.0.1
    Allow from .math.yourschool.edu
</Location>

Then save the file and quit (Save and File, Quit).

Just to be sure you changed what you wanted do run

# diff httpd.conf httpd.conf.bak1
# exit
$

diff should report the changes you made and only those.

Now start Apache

$su
<root password>
# /etc/init.d/httpd graceful
# 


and test your server by connecting to "http://localhost/" and/or connecting to your server from a browser on a remote machine. You should see the page Fedora Test Page indicating that apache is running. Connecting to "http://yourserver.yourdepartment.yourschool.edu/" on your server where yourserver.yourdepartment.yourschool.edu is the fully qualified hostname for your server gives the same page.

You can check Apache's status by connecting to "http://127.0.01/server-status" using a browser on your machine or from a browser on a remote machine in the math.yourschool.edu domain.

Further test Apache by connecting to "http://127.0.0.1/server-info" using a browser on your machine (or or from a browser on a remote machine in the math.yourschool.edu domain) and you will see a page listing various information about apache. In particular under Server Settings you should see

Server Version:  Apache/2.2.8 (Unix) DAV/2 mod_apreq2-20051231/2.6.1 mod_perl/2.0.3 Perl/v5.10.0

indicating that both mod_apreq2 and mod_perl are installed.


Configure Apache so that it starts at bootup.

  1. Select System, Administration and then Services
  2. Enter the <root password>
  3. Scroll down until you find httpd
  4. Select the httpd line and click Enable; this will start Apache automatically at bootup
  5. The http service should start and you will see a green dot.
  6. Then Quit

You can also use this Service Configuration window to stop, start, or restart Apache but I have found this difficult to use.

Now we edit httpd.conf one more time.

gedit httpd.conf

By default a ton of modules are loaded many which we don't require. We will comment out the ones we don't need

These modules are loaded by default

LoadModule auth_basic_module modules/mod_auth_basic.so
LoadModule auth_digest_module modules/mod_auth_digest.so
LoadModule authn_file_module modules/mod_authn_file.so
LoadModule authn_alias_module modules/mod_authn_alias.so
LoadModule authn_anon_module modules/mod_authn_anon.so
LoadModule authn_dbm_module modules/mod_authn_dbm.so
LoadModule authn_default_module modules/mod_authn_default.so
LoadModule authz_host_module modules/mod_authz_host.so
LoadModule authz_user_module modules/mod_authz_user.so
LoadModule authz_owner_module modules/mod_authz_owner.so
LoadModule authz_groupfile_module modules/mod_authz_groupfile.so
LoadModule authz_dbm_module modules/mod_authz_dbm.so
LoadModule authz_default_module modules/mod_authz_default.so
LoadModule ldap_module modules/mod_ldap.so
LoadModule authnz_ldap_module modules/mod_authnz_ldap.so
LoadModule include_module modules/mod_include.so
LoadModule log_config_module modules/mod_log_config.so
LoadModule logio_module modules/mod_logio.so
LoadModule env_module modules/mod_env.so
LoadModule ext_filter_module modules/mod_ext_filter.so
LoadModule mime_magic_module modules/mod_mime_magic.so
LoadModule expires_module modules/mod_expires.so
LoadModule deflate_module modules/mod_deflate.so
LoadModule headers_module modules/mod_headers.so
LoadModule usertrack_module modules/mod_usertrack.so
LoadModule setenvif_module modules/mod_setenvif.so
LoadModule mime_module modules/mod_mime.so
LoadModule dav_module modules/mod_dav.so
LoadModule status_module modules/mod_status.so
LoadModule autoindex_module modules/mod_autoindex.so
LoadModule info_module modules/mod_info.so
LoadModule dav_fs_module modules/mod_dav_fs.so
LoadModule vhost_alias_module modules/mod_vhost_alias.so
LoadModule negotiation_module modules/mod_negotiation.so
LoadModule dir_module modules/mod_dir.so
LoadModule actions_module modules/mod_actions.so
LoadModule speling_module modules/mod_speling.so
LoadModule userdir_module modules/mod_userdir.so
LoadModule alias_module modules/mod_alias.so
LoadModule rewrite_module modules/mod_rewrite.so
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_balancer_module modules/mod_proxy_balancer.so
LoadModule proxy_ftp_module modules/mod_proxy_ftp.so
LoadModule proxy_http_module modules/mod_proxy_http.so
LoadModule proxy_connect_module modules/mod_proxy_connect.so
LoadModule cache_module modules/mod_cache.so
LoadModule suexec_module modules/mod_suexec.so
LoadModule disk_cache_module modules/mod_disk_cache.so
LoadModule file_cache_module modules/mod_file_cache.so
LoadModule mem_cache_module modules/mod_mem_cache.so
LoadModule cgi_module modules/mod_cgi.so

Replace this list by the following Loadmodule list

LoadModule auth_basic_module modules/mod_auth_basic.so
# LoadModule auth_digest_module modules/mod_auth_digest.so
LoadModule authn_file_module modules/mod_authn_file.so
# LoadModule authn_alias_module modules/mod_authn_alias.so
# LoadModule authn_anon_module modules/mod_authn_anon.so
# LoadModule authn_dbm_module modules/mod_authn_dbm.so
# LoadModule authn_default_module modules/mod_authn_default.so
LoadModule authz_host_module modules/mod_authz_host.so
LoadModule authz_user_module modules/mod_authz_user.so
# LoadModule authz_owner_module modules/mod_authz_owner.so
LoadModule authz_groupfile_module modules/mod_authz_groupfile.so
# LoadModule authz_dbm_module modules/mod_authz_dbm.so
LoadModule authz_default_module modules/mod_authz_default.so
# LoadModule ldap_module modules/mod_ldap.so
# LoadModule authnz_ldap_module modules/mod_authnz_ldap.so
# LoadModule include_module modules/mod_include.so
LoadModule log_config_module modules/mod_log_config.so
LoadModule logio_module modules/mod_logio.so
LoadModule env_module modules/mod_env.so
# LoadModule ext_filter_module modules/mod_ext_filter.so
LoadModule mime_magic_module modules/mod_mime_magic.so
# LoadModule expires_module modules/mod_expires.so
# LoadModule deflate_module modules/mod_deflate.so
# LoadModule headers_module modules/mod_headers.so
# LoadModule usertrack_module modules/mod_usertrack.so
LoadModule setenvif_module modules/mod_setenvif.so
LoadModule mime_module modules/mod_mime.so
# LoadModule dav_module modules/mod_dav.so
LoadModule status_module modules/mod_status.so
LoadModule autoindex_module modules/mod_autoindex.so
LoadModule info_module modules/mod_info.so
# LoadModule dav_fs_module modules/mod_dav_fs.so
# LoadModule vhost_alias_module modules/mod_vhost_alias.so
LoadModule negotiation_module modules/mod_negotiation.so
LoadModule dir_module modules/mod_dir.so
# LoadModule actions_module modules/mod_actions.so
# LoadModule speling_module modules/mod_speling.so
# LoadModule userdir_module modules/mod_userdir.so
LoadModule alias_module modules/mod_alias.so
# LoadModule rewrite_module modules/mod_rewrite.so
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_balancer_module modules/mod_proxy_balancer.so
LoadModule proxy_ftp_module modules/mod_proxy_ftp.so
LoadModule proxy_http_module modules/mod_proxy_http.so
LoadModule proxy_connect_module modules/mod_proxy_connect.so
LoadModule cache_module modules/mod_cache.so
# LoadModule suexec_module modules/mod_suexec.so
# LoadModule disk_cache_module modules/mod_disk_cache.so
# LoadModule file_cache_module modules/mod_file_cache.so
# LoadModule mem_cache_module modules/mod_mem_cache.so
LoadModule cgi_module modules/mod_cgi.so

Then save the file and quit (Save and File, Quit) and restart Apache

# /etc/init.d/httpd graceful
# exit
$

Configuring MySQL

First become root and install the MySQL database.

$su
<root password>
# mysql_install_db --user=mysql
# exit
$

Start the MySQL service and configure it so that it starts at bootup.

  1. Select System, Administration and then Services
  2. Enter the <root password>
  3. Scroll down until you find mysqld
  4. Select it and click Enable; this will start MySQL automatically at bootup
  5. The MySQL service should start and you will see a green dot.
  6. Quit the Service Configuration window

Reboot and Test

Now reboot the system (System, Shut Down..., Restart) and login.

Now connect to "http://localhost/" using a browser on your machine and/or to your server from a browser on a remote machine. You should see the page Fedora Test Page indicating that apache is running.

This is also a good time to check that you can login your server from a remote location using SSH (non secure telnet and FTP are not allowed but secure SSH and SFTP are). If you are using "SSH Secure Shell" (now called "SSH Tectia"), a popular SSH client for PC's, you will have to add Keyboard Interactive to the list of "Authentication methods" under "Authentication" if it's not already there.

Finally test that MySQL is running.

$ mysql -u root
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 2
Server version: 5.0.51a Source distribution
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
mysql> 

Now type exit to quit

mysql> exit
Bye
$

Currently the MySQL password is empty so we didn't need a password. We will take care of that now.

MySQL Security Issuses

As initially set up, MySQL is a very open system. There are anonymous accounts with full privileges for some databases and the root accounts are not password protected. See e.g. http://dev.mysql.com/doc/refman/5.0/en/default-privileges.html for information on this. We recommend removing the anonymous accounts and giving passwords to the root accounts. There are two root accounts, one is root@localhost and the other is root@host_name where host_name is the name of your server. To find this name, do the following

$ mysql -u root
mysql> SELECT Host, User, Password FROM mysql.user;

You will see a table with five entries. For localhost you will see two Users, root and one with an empty name (the anonymous user). The other listed Host (with the same two users) is the name of your server which we will denote by host_name. Finally you will see the host 127.0.0.1 with the root user.

We will exit MSQL and run a script to make it more secure.

mysql> exit
Bye
$su
<root password>
# /usr/bin/mysql_secure_installation

The current MYSQL root password is empty so just hit <Enter> for the password. Now answer Yes (Y) to all prompts. When prompted enter your choosen MySQL root password. As was said above, "Do not forget what you enter here". Also remember that this is the password for the MySQL root user, not the Fedora linux system root user. Below we refer to this as <mysql root password>.

Finally we secure the MySQL server by disallowing access via TCP/IP. To do this we have to edit the MySQL configuration file my.cnf .


# cd /etc
# cp my.cnf my.cnf.bak1
# gedit my.cnf
  1. Under the line old_passwords=1 add the new line
  2. skip-networking

Then save the file and Quit. And exit from the root account

# exit
$

That's it. Now the only access to the MySQL server is via the mysql.sock file. Test that all is well:

$ mysql -u root -p 
Enter Password: <mysql root password>

You should see

Welcome to the MySQL monitor ...
mysql>

Enter

mysql> exit
Bye
$


and congratulate yourself. You are now ready for the next and hopefully easy part, installing WeBWorK.

Downloading the WeBWorK System Software and Problem Libraries

We are finally at the point where we can start downloading and installing WeBWorK. We will use CVS to download WeBWorK. This is easy and it will also make it easy to update the system in the future. Note that the following are rather long commands; it is much easier to copy (^C) them from this document and paste (<Shift> <Ctrl> <V>) them in a terminal window

$ cd
$ cd downloads

$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout -r rel-2-4-patches webwork2 pg
$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/npl checkout NationalProblemLibrary

The first download gives you the latest released version with patches. The second download contains the WeBWorK National Problem Library. This now includes the Rochester and Union Libraries along with others as sub libraries. Your system will be loaded with many thousands of WeBWorK problems (over 16,000 currently).

Installing WeBWorK

Move the System into the Required Directories

As root create a webwork directory under /opt and move directories there.

$ su
<root password>
# mkdir /opt/webwork
# mv webwork2 /opt/webwork/
# mv pg /opt/webwork/

Now create the courses and libraries directories under webwork and copy and move content there.

# mkdir /opt/webwork/courses
# mkdir /opt/webwork/libraries
# mv NationalProblemLibrary /opt/webwork/libraries/
# cd /opt/webwork/webwork2/courses.dist
# cp *.lst /opt/webwork/courses/
# cp -r modelCourse/ /opt/webwork/courses/

Setting Permissions

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

# cd /opt/webwork/pg
# chown -R root:root .
# chmod -R u+rwX,go+rX .

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

# cd /opt/webwork/webwork2
# chown -R root:root .
# chmod -R u+rwX,go+rX .

Certain data directories need to be writable by the web server. These are DATA, courses, htdocs/tmp, logs, and tmp. It is convenient to give WeBWorK administrators access to these directories 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 create a new group called wwdata, containing both the WeBWorK administrators and the web server.

  1. Select System, Administration and then Users and Groups
  2. Enter the <root password>
  3. Click Add Group
  4. For Group name enter wwdata and click OK
  5. Click Groups and select wwdata
  6. Click Properties and then click Group Users
  7. Check yourself and apache and then click OK
  8. Close the User Manager


If there are other users who will also be administering WeBWorK files, now is a good time to add them. And remember to add them to the wwdata group as above.

You can check that this succeeded in a terminal window by entering

# exit
$ id <your userid>

and then you should see wwdata listed under groups. Also

$ id apache

should show wwdata listed under groups. Now we make the WeBWorK directories that need to be writable by the web server have wwdata as their group. The following are rather long commands; you might want to copy them and paste them into your terminal window rather than typing them.

$ su
<root password>
# cd /opt/webwork/webwork2/
# chgrp -R wwdata 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 ! -name CVS -exec chmod g+s {} \;
# exit
$

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 bin directory to your path. This will allow you to run WeBWorK command-line utilities without typing the full path to the utility. Goto your home directory and backup your .bashrc file

$ cd
$ cp .bashrc .bashrc.bak1

Now edit .bashrc

$ gedit .bashrc

After the last line add the two lines:

export PATH=$PATH:/opt/webwork/webwork2/bin
export WEBWORK_ROOT=/opt/webwork/webwork2

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

Checking Module Dependancies

WeBWorK includes a script called check_modules.pl 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

Scroll up and look through the listing. It should find everything except PHP::Serialization, SOAP::Lite, MIME::Parser and XMLRPC::Lite which are only required if you plan to use WeBWorK with Moodle and tth which is a deprecated display mode. If something is missing (flagged by **), look back through these instructions and/or look at to find where it should have been installed and install it. Note you may have to search in Installation Manual for 2.4 to find out what package it is contained in.

Configuring WeBWorK

Making Copies of the Distribution Configuration Files

Before configuring the system, you must make local copies of the global.conf and database.conf configuration files, located in /opt/webwork/webwork2/conf/ . Since these are owned by root

$ su
<root password>
# cd /opt/webwork/webwork2/conf
# cp global.conf.dist global.conf
# cp database.conf.dist database.conf

Global Configuration

Most WeBWorK configuration is done in the file /opt/webwork2/conf/global.conf. This file provides system-wide configuration settings, and defaults for course settings. Any setting in this file can be overridden in the course.conf file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in global.conf) in the course.conf file.

There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. Now edit global.conf

# cd /opt/webwork/webwork2/conf
# gedit global.conf

WeBWorK uses the DateTime module. DateTime is supposed to be able to determine the local timezone itself without you having to enter it but this often fails so it is best to just set it here. For is a list of timezones recognized by DateTime go to http://search.cpan.org/dist/DateTime-TimeZone/ . These timezones are more refined than standard timezone usage in that they include switches to daylight savings time (e.g. some parts of a time zone may make the switch and others may not). For example if your server is in the eastern US, on the list you will see DateTime::TimeZone::America::New_York and you should replace $siteDefaults{timezone} = ""; by $siteDefaults{timezone} = "America/New_York";

  1. Search for $siteDefaults{timezone} = ""; and enter your local timezone.

At this point TtH is a deprecated display mode which we didn't install so we have to remove it from the listof possible display modes.

  1. Search for formattedText and comment out the line "formattedText", # format math expressions using TtH

so it becomes

#   "formattedText", # format math expressions using TtH

We need to set a password that WeBWorK uses when it communicates with the MySQL database. Note that this is not the same as the <mysql root password> which is the password the MySQL root user uses.

  1. Search for $database_password = ""; and replace this by
    $database_password = "database_password";

where of course you should replace 'database_password' with your own password. Remember this password as we will need it below.

WeBWorK sends mail in three instances. The PG system sends mail to report answers to questionnaires and free-response problems. The mail merge module is used to send mail to course participants, i.e. to report scores. The feedback module allows participants to send mail to course instructors.

To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. If the local machine is running an SMTP server, use localhost. IMPORTANT: Our instructions above did not install an SMTP server so you will have to install and configue one if you do not use your school's SMTP server. When connecting to the SMTP server, WeBWorK must also send an email address representing the sender of the email (this has nothing to do with the From address on the mail message). Edit the lines

$mail{smtpServer}            = 'mail.yourschool.edu'; 
$mail{smtpSender}            = 'webwork@yourserver.yourschool.edu';

entering the appropriate information.

If you want WeBWorK questionnaires or similar things from different courses to be mailed to a central person or persons (e.g. the WeBWorK administrator), edit the lines

$mail{allowedRecipients}     = [
   #'prof1@yourserver.yourdomain.edu',
   #'prof2@yourserver.yourdomain.edu',
];

appropriately where you should use the professor(s) actual email address(es). In order to have professors from individual courses receive such email, this should be set in course.conf to the addresses of professors of each course.

Then save the file and Quit.


Now become a regular user again

# exit
$

WeBWorK uses a single database, called webwork, for all courses. We will create the webwork database now.

To do this do the following (before you just copy, paste and hit <Enter> notice that you have to replace database_password with the password you set when editing global.conf above):

$ mysql -u root -p mysql
Enter password: <mysql root password>
mysql> CREATE DATABASE webwork;
mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, LOCK TABLES ON webwork.* TO webworkWrite@localhost IDENTIFIED BY 'database_password';
mysql> exit
Bye
$ 

where as we said replace database_password with the password you set when editing global.conf above.

Since version 2.3.0 WeBWorK has an automatic database upgrade system. Rather than manually issuing SQL commands to make changes to the database, or using ad-hoc scripts like wwdb_addgw, there is a single script called wwdb_upgrade that applies any necessary updates. It should be run when creating a new database, and any time you upgrade WeBWorK.

$ /opt/webwork/webwork2/bin/wwdb_upgrade -v

jsMath Settings

Version 2.0 of jsMath introduced a new fallback method for when the TeX fonts are not available on the student's computer. This uses images of the individual TeX characters in place of the TeX fonts. These are distributed in webwork2/htdocs/jsMath/jsMath-fonts.tar.gz, and you need to unpack this tarball before jsMath will work properly. Use the command

$ su
<root password>
# cd /opt/webwork/webwork2/htdocs/jsMath
# tar vfxz jsMath-fonts.tar.gz

This will unpack the archive. Since there are 20,000 tiny files, it can take a little while, so the v option is used to show you the names as they are unpacked so that you know the command is actually doing something. Once the images are unpacked, jsMath's image mode fallback (the default fallback method) will work properly.

Configuring Apache

WeBWorK ships with an Apache config file that needs to linked into your Apache configuration process. The file is named webwork.apache2-config.dist and located in the conf directory. First, copy the file to webwork.apache2-config:

# cd /opt/webwork/webwork2/conf
# cp webwork.apache2-config.dist webwork.apache2-config

and now link it into your Apache configuration process

# cd /etc/httpd/conf.d
# ln -s /opt/webwork/webwork2/conf/webwork.apache2-config webwork.conf

Next we will make a few changes to Apache's default configuration.

  1. cd /etc/httpd/conf
  2. gedit httpd.conf

Search for the line

Timeout 120

and replace it by

Timeout 1200

Next seach for the lines

    MaxClients          256
    MaxRequestsPerChild   4000

Which occur under <IfModule prefork.c and replace them by

# For WeBWorK a rough rule of thumb is 20 MaxClients per 1 GB of memory
    MaxClients           20
    MaxRequestsPerChild  100

where you should set MaxClients depending on the amount of memory your server has.

Then save the file and quit.

Then restart Apache

# /etc/init.d/httpd graceful
# exit
$

Test your configuration

  1. Test the /webwork2 location by visiting http://yourserver.yourschool.edu/webwork2. You should see the WeBWorK home page with no courses listed. Actually the directory /opt/webwork/courses/ does contain the modelCourse but the modelCourse is not a real course so you will get an error message if you try to log into it. It will be used a as model for setting up other courses. For this reason /opt/webwork/courses/modelCourse/ contains a file named hide_directory and so the modelCourse is not visible.
  2. Test the /webwork2_files location by visiting http://yourserver.yourschool.edu/webwork2_files. You should see the "WeBWorK Placeholder Page".
  3. You cannot test the /webwork2_course_files location until you have created a course.

If Something is Wrong

If something is wrong one of the first things to check is that the config files have been edited correctly (e.g. one time a wrapped line in global.conf caused me problems). A quick way to check this is to do a diff between the edited and distributed versions and check that diff reports the changes you made and only those.

# exit
$
$ cd /etc/httpd/conf
$ diff httpd.conf httpd.conf.bak1
$ cd /opt/webwork/webwork2/conf/
$ diff global.conf global.conf.dist
$ diff database.conf database.conf.dist
$ diff webwork.apache2-config webwork.apache2-config.dist 

If something is wrong and you fix it, you will have to restart Apache for the changes to take effect

$ su
Password: <root password>
# /etc/init.d/httpd graceful
# exit
$

---

Create the admin Course

The CourseAdministrationManual gives information about creating courses. Here we will give explicit instructions for doing this.

$ su
Password: <root password>
# newgrp wwdata
# umask 2
# cd /opt/webwork/courses
# /opt/webwork/webwork2/bin/addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin
# exit
# exit
$

Now goto http://yourserver.yourschool.edu/webwork2 and should see the WeBWorK home page with Course Adninistration listed at the top. Click on it and login with Username admin and Password admin . This first thing you should do is to click on Password/Email and change admin 's password to something more secure than admin .

Unless you choose otherwise, users with professor privilges in the admin course (i.e. WeBWorK administrators) will automatically be added to new courses with professor privilges 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. Check Add 1 student(s) and click Take Action!
  3. Enter the appropiate information (you can leave the last three items blank) and click Add Students
  4. Click on Classlist Editor in the left panel again
  1. When you enter a new student, by default their Student ID is used as their password. We'll change this now.
  2. Select yourself with a check mark and then check Give new password to Selected users or just check Give new password to All users (as a safely mechanism you can not change the password for the user you are logged in as, currently admin, this way) and then click Take Action!
  3. Enter the password, check Save changes and then click Take Action!
  4. Finally give yourself professor privilges by selecting yourself with a check mark, checking Edit Selected users 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)
  5. Now at the far right change Permission Level from student to professor
  6. Check Save changes and then click Take Action!

At some point you will probably want to hide the admin course so that it is not listed on the WeBWorK home page. As we noted above the modelCourse, which is already hidden, is not a real course so you will get an error message if you try to log into it. This is a good reason to hide it. The modelCourse is very useful as a model (hence its name) for setting up other courses. The admin course is used for administering WeBWorK and even though regular users can not log into it (you did change the admin password, didn't you!!), it a little bit cleaner and safer to hide it from prying eyes. To hide a course place a file named hide_directory in the course directory and it 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 admin course using the URL http://yourserver.yourschool.edu/webwork2/admin but you will not see a link for it on the WeBWorK home page http://yourserver.yourschool.edu/webwork2 . Let's hide the admin course.

$ sudo cp /opt/webwork/courses/modelCourse/hide_directory /opt/webwork/courses/admin
password:<your password>

Now goto http://yourserver.yourschool.edu/webwork2 and no course will be listed.

Starting and Stoping Apache, MySQL and the GNOME desktop GUI

If you make changes to the system, you will have to restart apache2 before the changes take effect. On rare ocassions you may need to restart MySQL.

Starting and Stoping Apache

You have to run these commands as root.

To start or restart (i.e. stop and then start) the apache2 webserver run the command

$ sudo /etc/init.d/httpd graceful
password:<your password>

To stop the apache webserver run the command

$ sudo /etc/init.d/httpd stop
password:<your password>

You can also start,stop or restart apache2 by using the GUI interface.

  1. Select System, Administration and then Services
  2. Enter the <root password>
  3. Scroll down to httpd and select it
  4. The Status window will give the status of apache2
  5. Click Start, Stop or Restart
  6. Click OK to acknowledge the message

Starting and Stoping MySQL

You have to run these commands as root.

To start the MySQL server run the command

$ sudo /etc/init.d/mysqld start
root's password:<root password>

To stop the MySQL server run the command

$ sudo /etc/init.d/mysqld stop
root's password:<root password>

To restart the MySQL server run the command

$ sudo /etc/init.d/mysqld restart
root's password:<root password>

You can also start,stop or restart MySQL by using the GUI interface.

  1. Select System, Administration and then Services
  2. Enter the <root password>
  3. Scroll down to mysqld and select it
  4. The Status window will give the status of apache2
  5. Click Start, Stop or Restart
  6. Click OK to acknowledge the message

Starting and stopping the GNOME desktop GUI

The GNOME desktop is automatically started when the system boots.

%RED% NOTE: The following instructions work in Debian but not in Fedora 7. I haven't found an easy way to stop and start the GNOME desktop GUI in Fedora. %ENDCOLOR%

To stop GNOME so that you only have a standard terminal window run the following in a standard terminal window

$ sudo /etc/init.d/gdm stop 
password:<password>

If you stopped GNOME and want to restart it run the following in a standard terminal window

$ sudo /etc/init.d/gdm start 
password:<password>

Install the WeBWorK Problem Libraries

Before we create a real course we will install the WeBWorK Problem Libraries.

Install the National Problem Library

The National 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 tell WeBWork where to find it.

Edit global.conf.

$ cd /opt/webwork/webwork2/conf
$ su
Password: <root password>
# gedit global.conf

Search for problemLibrary and replace $problemLibrary{root} = ""; by
$problemLibrary{root} = "/opt/webwork/libraries/NationalProblemLibrary";

Then save the file and quit. And return to a regular user

#exit
$

Run the NPL-update script making sure you are in the /opt/webwork/libraries/NationalProblemLibrary directory. This directory contains the files loadDB2 and create_tables2.sql.

$ cd /opt/webwork/libraries/ProblemLibrary
$ NPL-update

This has to convert a lot of data (around 16900 files) so please be patient; it can take a long time.

If at some time in the future you want to upgrade the Problem Library, the process is simpler. Optionally remove the previous copy of the library, unpack the new copy in the same place, and run NPL-update.

Set up the Rochester and Union Libraries

First we need to edit global.conf one last time

$ cd /opt/webwork/webwork2/conf
$ su
Password: <root password>
# gedit global.conf
  1. Search for courseFiles{problibs} and scroll down several lines to the line
    # rochesterLibrary => "Rochester",
  2. Uncomment this line (i.e. remove the #) so it becomes

         rochesterLibrary => "Rochester",

  1. Directly below this line add the line

         unionLibrary => "Union",

  1. Search for macrosPath and scroll down several lines to the line
    $pg{directories}{macros},
  2. After this line add the line:
    '/opt/webwork/libraries/NationalProblemLibrary/macros/Union',

Don't forget the coma (,) at the end of these lines. Then save the file and quit.

Since we have edited global.conf a lot and this is a very critical file, it would be a good idea to run


# exit
$ diff global.conf global.conf.dist

and check that you haven't made any mistakes (e.g. by introducing an inadvertant line break, etc).

We next put links to the Rochester and Union Libraries in the modelCourse so that when we create courses copying templates from the modelCourse, these libraries will be available. Skip this step if you usually only want to use National Problem Library.

$ cd /opt/webwork/courses/modelCourse/templates/
$ sudo ln -s /opt/webwork/libraries/NationalProblemLibrary/Union unionLibrary
password: <your password>
$ sudo ln -s /opt/webwork/libraries/NationalProblemLibrary/Rochester rochesterLibrary

If you want to put another library into the modelCourse, just do the analogous thing. If you just want the additional library in a particular course, add the link in the templates directory of that course. If you look in the directory /opt/webwork/libraries/database_problems/ you might find other libraries that are not yet listed in global.conf (like Union above) and these can be added in the same way we added Union. Usually they do not require additional macros like Union did. Finally if you add a library with non standard symbols in the name (e.g. uva-statLibrary) you have to use single quotes when adding it to global.conf, e.g.
         'uva-statLibrary' => "UVA-Stat",
It's easier to just avoid such names.

Create Your First Actual Course

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 checked
  6. Add an additional instructor if you wish
  7. Copy templates from: modelCourse (the default action)
  8. Select sql_single for the database layout.
  9. Click on Add Course
  10. Click Log into myTestCourse

and log in either as admin or yourself.

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

Test that Things are Working Properly

We will test out a few important parts of WeBWorK. If you run into problems, you should look at the Apache error log which is located at /etc/httpd/logs/error.log.

Click on Hmwk Sets Editor on the Main Menu. Then select (by clicking the circle button) Import, select setDemo.def from the from drop down list and select all current users from the assigning this set to drop down list. Then hit Take Action!

Now click on Homework Sets on the Main Menu and click on Demo. Then look at the problems. Mathematical equations should be typeset. If not, edit the file Constants.pm in the directory /opt/webwork/webwork2/lib/WeBWorK. Change the line $WeBWorK::PG::ImageGenerator::PreserveTempFiles = 0; to ...::PreserveTempFiles = 1;. Then restart Apache and view the first couple problems or some new ones. Then look in the directory /opt/webwork/webwork2/tmp/. cd to one of the ImageGenerator.../tmp/ directories and look at the error and log files there. When you fix the problem remember to edit ...::PreserveTempFiles = 1; back to 0 and restart Apache or you will be saving a lot of unnecessary files. Another useful trick is to try downloading a hard copy of an assignment and then (assuming there are errors) looking at the various log files that are linked to on the output page.

When you continue looking at problems you will get an error when you try to look at Problem 6 because we have not configured the CAPA macros which are required to display CAPA problems. Unless you are teaching physics you probably don't need them. Also in Problem 9 the Java applet will not load. Problem 9 was written in the 90's and used an applet on a server at The Johns Hopkins University. The server went away a long time ago but have retained this problem for historical reasons and also because it is a example of several things (e.g. WeBWorK problems can include applets running on remote servers but this can lead to other problems).

Next click on Prob. List to bring back the Problem List Page and click on Download a hardcopy of this homework set. The page is a little complicated because you are a professor but you can just scroll to the bottom and click on Generate hardcopy for selected users and selected sets. You will get an error (because of the bad Problem 6) but just click Download Hardcopy to get what was generated. Also you can see links to various informational files that are available if you run into problems (normally these files are removed if there are no errors).

Another thing to do is to use Email on the Main Menu. Again this page is a little complicated because you can do a lot of things with it (including mail merge) but at this point just select yourself in the list to the right and hit Send Email at the bottom. You should receive two emails. One is the message you just sent and the other is an email with subject "WeBWorK email sent" giving information on your mailing.

As a final test click on Library Browser on the Main Menu. Click Problem Library and select a Subject, Chapter and Section and then hit View Problems. The first 20 of your selected problems will be displayed. You can also test that you can access any additional Problem Libraries that you installed.

If all the above tests work, you can be pretty confident that WeBWorK is working properly.

Go back to Hmwk Sets Editor on the Main Menu. Then select (by clicking the circle button) Import, select setOrientation.def from the from drop down list and select all current users from the assigning this set to drop down list. Then hit Take Action!. Then go through the Orientation problems. This is a good first set to use for introducing students to WeBWorK.

If you are new to WeBWorK, you should probably add a regular student to myTestCourse and log in as that student to see what the student interface looks like. It's much simpler than the professor interface. Click on Classlist Editor on the Main Menu. Then select (by clicking the circle button) Add 1 student(s)and hit Take Action!. Add one student, say Jane Smith, with Student ID 1234 and Login Name jsmith. Jane Smith's initial password will be her Student ID 1234. Now login as Jane Smith and play around a little.

Where to go From Here

You should play around with myTestCourse e.g. click on Library Browser and browse the Problem Library and also the Rochester and Union libraries.

Look at [[3]]

Read the CourseAdministrationManual for more information about creating courses.

Consult the WeBWorKDocs topic for other WeBWorK documentation.

-- Main.ArnoldPizer - 21 June 2007 Initial version based on Sam Hathaway's InstallationManualV2pt3