Difference between revisions of "User talk:Glennric"

Latest revision as of 08:13, 4 December 2019

Welcome to WeBWorK! We hope you will contribute much and well. You will probably want to read the help pages or [help pages]. Again, welcome and have fun! gage 18:14, 18 September 2014 (EDT)

Difference between revisions of "User talk:Glennric"

Latest revision as of 08:13, 4 December 2019

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Documentation for

NAVIGATION

Tools

@@ Line 3: / Line 3: @@
 You will probably want to read the [[Help:Contents|help pages]] or [[https://www.mediawiki.org/wiki/Help:Contents help pages]].
 Again, welcome and have fun! [[User:Gage|gage]] 18:14, 18 September 2014 (EDT)
-== Installation Manual for 2.15 on Ubuntu 18.04 ==
-These instructions cover the installation of the Ubuntu Linux 18.04 LTS operating system and WeBWorK 2.15 from scratch.
-Other installation methods (which are faster and easier) include using the WeBWorK install script ww_install (see https://github.com/openwebwork/ww_install), the WeBWorK Live DVD (see [[Installing_from_WW2.13_Ubuntu16.04_Vanilla_LiveDVD]]) or the WeBWorK Virtual Machine Image (see [[Installing_from_WW2.13_Ubuntu16.04_Vanilla_Virtual_Machine_Image]]).
-If you are just upgrading WeBWorK, especially if you already have existing WeBWorK courses, see [[Upgrading_WeBWorK_with_Github]].
-== Notation ==
-First some short comments on notation we will be using. We will use <code>&lt;key&gt;</code> to indicate that you should press a specific key (e.g. <code>&lt;Enter&gt;</code>, <code>&lt;Tab&gt;</code>, <code>&lt;F12&gt;</code>, etc.).  Sometimes we will also use e.g. <code>&lt;wwadmin password&gt;</code> to indicate you have to enter the wwadmin password.
-<code>^</code> will indicate the <code>&lt;Ctrl&gt;</code> key so e.g. <code>^X</code> is really shorthand for <code>&lt;Ctrl&gt; &lt;X&gt;</code>, i.e. press the Ctrl key and hit the X key.
-== Installing the Ubuntu 18.04 Linux Operating System ==
-===Installation DVD ===
-Obtain the <code>Desktop Edition</code> installation DVD/CD set.  Connect to http://www.ubuntu.com/ for information. For example you can download an ISO image of the installation DVD and then burn your own installation DVD.  You want the file <code>ubuntu-18.04-desktop-amd64.iso</code>.  '''Note 1:''' We recommend you use the "Long Term Support" (LTS) version of Ubuntu which is currently version 18.04; the next LTS release will be version 20.04 to be released in April, 2020. '''Note 2:''' We recommend you actually use the latest 18.04 iso file which is currently <code>ubuntu-18.04-desktop-amd64.iso</code>.  Choose which ever download site works best for you; I have had good luck with http://mirrors.kernel.org/ubuntu-releases/  If you download the ISO image, make sure that you verify the integrity of the downloaded file by comparing the MD5 checksum of the downloaded file with the MD5 checksum listed at https://help.ubuntu.com/community/UbuntuHashes or at the download site  (e.g. http://mirrors.kernel.org/ubuntu-releases/18.04). These instructions will assume you have the <code>ubuntu-18.04-desktop-amd64.iso</code> installation DVD but installing from an alternate DVD, a commercial DVD/CD set or from the net should be essentially identical.
-You will want to have you computer connected by ethernet to the internet for the installation. Place the installation CD in your DVD/CD drive and reboot your computer from the DVD drive.  You may have to press a key (e.g. <code>&lt;F12&gt;</code>) 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. See https://help.ubuntu.com/community/BootFromCD for help.
-After the system boots you will be presented with a series of 7 steps.
-;Step 1
-: On the first install panel keep English as the selected language and click <code>Install Ubuntu</code>, the second (to the right) option.
-;Step 2
-: Just hit <code>Continue</code> on the next page
-===Optional Configurations===
-If you will have a large number of users (say over a 1,000) and/or a slow server, you may want to consider the first two optimizations. They are independent but related and deal with how WeBWorK handles various temporary and static files. We call these two options '''Optional A''' and '''Optional B'''. The third option, '''Optional C''', gives greater security.
-'''Optional A''' creates a separate partition (or directory) on which are stored all of WeBWorK's "temporary" files.  These are mostly small files such as png images of equations, pdf files, etc that may be reused but if they are not present (e.g. if they get deleted) they will be seamlessly regenerated on the fly. There is no reason to back up such files and having them in a separate partition or directory means that it is easier and faster to back up other partitions and skip backing up unnecessary files. ''Even if you do not want to set up a separate partition for this, it is very convenient to at least set up a separate directory for these temporary files and we recommend that you do so. But this is something you do after WeBWorK is installed.''
-'''Optional B''' installs and configures a lightweight webserver. Apache is a very standard and powerful webserver which we use to serve WeBWorK pages.  However its child processes use a lot of resources (e.g. memory).  When serving static files and images, a much lighter weight webserver can be used. This can substantially reduce the load on a heavily used server.
-'''Optional C''' configures Apache (and lighttpd if installed) so that access to WeBWorK will be through an encrypted Secure Sockets Layer (SSL) with an https: URL.
-Except for creating a separate partition, we will wait until WeBWorK is installed and tested before implementing these options. We mention them here because the next step is partitioning the disks.
-===Partition disks===
-;Step 3
-:Next comes the <code>Installation type</code> page.  You should be able to accept the defaults unless you want to follow '''Optional A''' and/or create separate partitions for various directories.   There is a lot of information on the web if you don't want to accept the default partition set up. If you want to implement '''Optional A''' follow the directions below. '''Note''' that if you only want to implement Optional A with a separate directory, not a separate partition, you don't have to do anything special with partitions at this point.
-'''Optional A''': The default partitioning scheme creates just two partitions, a root (<code>/</code>) partition and a swap partition. Here we will create those and an additional partition for WeBWorK's temporary files.
-# On the <code>Installation type</code> page select <code>Something else</code> and then hit <code>Continue</code>. This will bring you to the partition page where you can choose a new partition table, resize partitions, etc.
-Now you have to decide how to allocate your disk space.  The rule of thumb is to use twice the amount of RAM you have for swap (e.g. 4 GB if you have 2 GB of RAM but you can allocate less if you have a lot of RAM).  For WeBWorK's temporary files 25 GB for every 1,000 students should be ample. You can allocate the remainder of your disk space to the root (<code>/</code>) partition.  Actually if you are going through the trouble of doing this, you probably will want to research other partitioning recommendations.
-# For the main, root partition, under the <code>Use as:</code> drop down list select <code>Ext4 journaling file system</code> and under the <code>Mount point:</code> drop down list select <code>/</code>
-# For the swap partition, under the <code>Use as:</code> drop down list select <code>swap area</code>
-# For WeBWorK's temporary files partition, under the <code>Use as:</code> drop down list select <code>Ext4 journaling file system</code> and under the <code>Mount point:</code> drop down list select <code>/var/www/html/wwtmp</code>
-Finally
-# Review your changes and
-# Select <code>Continue</code>
-At the bottom of this page you have options on installing the boot loader but you almost certainly want to use the defaults.
-===Continue Initial Installaion===
-;Step 3
-: Select the partition you want to install Ubuntu in and hit <code>Continue</code>
-;Step 4
-: Select a city in your time zone and hit <code>Continue</code>
-;Step 5
-: Hit <code>Continue</code> to accept the default keyboard layout
-;Step 6
-: The next panel asks "Who are you?". What you fill in here is a privileged user so you might want to enter a special administrative account rather than your normal account.  We suggest <code>&lt;wwadmin&gt;</code> but you can use whatever you want.
-* Enter the information for "Your name"
-* Enter the information for "Your Computer's name"
-* Enter the information for "Pick a username" In these instructions, we will call this name <code>&lt;wwadmin&gt;</code>.
-* Enter the information twice for the password.  In these instructions, we will call this password the <code>&lt;wwadmin password&gt;</code>. '''Do not forget what you enter here.'''
-* Then hit <code>Continue</code> to continue
-;Step 7
-: If the page about importing accounts appears just hit <code>Continue</code> to continue without importing anything
-Now sit back and relax while the installation takes place.  Some of the steps can take a long time. Please be patient. When you finally see "Installation is complete" hit <code>Restart now</code>.
-===Continue Installation ===
-After this finishes the system will ask you remove the DVD and then press <ENTER>.
-# Log into your account
-# At some point the <code>Software Updater</code> icon may appear. If it does, open it and accept all updates. Alternately you can open <code>Show Applications</code> (the bottom icon on the left side), type <code>Update</code> and open the <code>Software Updater</code>.  Click <code>Install Now</code>. You may have to enter the <code>&lt;wwadmin password&gt;</code> which functions as the <code>&lt;root password&gt;</code> and click <code>Authenticate</code>.  Follow any instructions, e.g. you may be told to reboot as soon as the installation is completed (to reboot, click on the power button icon in the upper right hand corner, then select  <code>Restart</code>)
-===Test Browser, Network and Keyboard ===
-After reboot and login, click the Firefox icon at the left of the screen and you should be connected to the world.  Go to http://webwork.maa.org/wiki/Installation_Manual_for_2.13_on_Ubuntu_18.04 where you can view this document and, if you want, copy commands that you need (see below).
-If something is wrong and you are not connected to the web, the first thing to do is check the network information.
-# select <code>Show Applications</code> and type <code>Network </code>
-# Select the wired connection under Ethernet and hit <code>Edit</code> and look and see if everything is set up correctly and correct any errors
-# If no connection is set up click <code>Add</code> and then enter your servers IP address, Netmask (usually 255.255.255.0 but possibly 255.255.0.0) and Gateway address (often the same as the IP address with the last number replaced by 1).  Important: after entering a number hit the <code>&lt;Enter&gt;</code> key so that the change is recorded.
-# Next enter the IP address(es) of your DNS server(s)separated by spaces.  You need to enter at least one DNS server
-# Finally enter the search domain <code>Hosts</code>
-# Click <code>Save</code>
-# Enter <code>&lt;wwadmin password&gt;</code> and click <code>Authenticate</code>
-# Click <code>Close</code>
-Your network connection should start up almost immediately. If you are still having problems first try rebooting (click on the power button button icon in the upper right hand corner, then select <code>Restart</code>) and if that doesn't work it's time to investigate further or seek help.
-Here's an aside on keystroke delay and repetition rate.  If you find the keystroke delay too short (so that you often type "geeet" when you want to type "get"), do the following.  select <code>Show Applications</code> and type <code>Settings</code>.  Now select <code>Universal Access</code>, <code>Typing</code>, <code>Repeat Keys</code> and then increase the delay time interval and close the window.
-== Terminal Window Notation and Use ==
-Before installing and configuring additional software, we need to talk about terminal windows.
-To open a terminal window select <code>Show Applications</code> (the bottom icon on the left side) and type <code>Terminal</code>. The next time you select <code>Show Applications</code>, the terminal icon might be displayed.  Or you can just type <code>&lt;Ctrl&gt; &lt;Alt&gt; &lt;T&gt;</code>.
-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 <code>&lt;Enter&gt;</code>. 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.
-<code>ch</code>) and hit <code>&lt;tab&gt;</code> 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 <code>ch</code>) nothing will
-happen (except you may hear a beep) and you can type more letter(s) and hit <code>&lt;tab&gt;</code> again. Or you can
-hit <code>&lt;tab&gt;</code> a second time and you will see a list of all possible
-completions. E.g. entering <code>ch&lt;tab&gt;&lt;tab&gt;</code> gives a list of possible
-completions and <code>ch&lt;tab&gt;gr&lt;tab&gt;</code> (or <code>chgr&lt;tab&gt;</code>) gives <code>chgrp</code>, 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 <code>copy</code> from the Edit dropdown list or <code>^C</code>) and paste them into a terminal window
-(with <code>paste</code> from the Edit dropdown list or <code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code>. Note that <code>&lt;Shift&gt; &lt;Insert&gt;</code> also works).  This is an excellent way to use these instructions since it is fast and insures commands are entered correctly (just be careful to read before you run the command and replace things like <code>database_password</code> with the correct code in the few places such things occur).
-For our first terminal window task create a <code>downloads</code> directory where we will keep copies of downloaded software.
- $ cd
- $ mkdir downloads
-== Running commands as root ==
-By default Ubuntu has no password set for the root user. To gain root access you have to use the <code>sudo</code> command with the <code>&lt;wwadmin password&gt;</code>. This is the password you set for the first user which we called the WeBWorK administrator <code>&lt;wwadmin&gt;</code> while installing Ubuntu.
-To run commands as <code>root</code> use the <code>sudo</code> command
- $ sudo <command>
- [sudo] password for wwadmin: <wwadmin 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;wwadmin password&gt;</code>.  A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> .
-You can also use sudo to become root and get the root prompt #. To do this run
- $ sudo su
- [sudo] password for wwadmin: <wwadmin password>
- #
-When you want to exit the root prompt and return to being a regular user, do the following
- # exit
- exit
- $
-==Ubuntu Software Packages ==
-Our next task is to install a number of Ubuntu software packages.  '''For a very fast way to do this, copy the command at the end of this section, paste it into a terminal window and run it as root.''' Or you can go through the step by step process using the <code>Synaptic Package Manager</code> as follows.
-First of all most Debian based Linux distributions rely on a program called Synaptic Package Manager to install software. However, as of Ubuntu 11.10, Synaptic has been removed from Ubuntu in favor of the Ubuntu Software Center. You can use the Ubuntu Software Center if you wish but I'll give instructions for using Synaptic Package Manager.  Note that what I really do is use the '''very fast way''' noted above.
-First we have to install the Synaptic Package Manager
- $ sudo apt install synaptic
- [sudo] password for wwadmin: <wwadmin password>
-Just hit <code>&lt;Enter&gt;</code> to accept the defaults.  After the installation is complete
-# Select <code>Show Applications</code> and type <code>Synaptic and click on the <code>Synaptic Package Manager</code> icon.   You will have to enter the <code>&lt;wwadmin password&gt;</code>. The <code>Synaptic Package Manager</code> window will open
-# Click on <code>Reload</code> 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 <code>libnet-ldap-perl</code> and then just give the list of required packages.
-# Select <code>Search</code>
-# Under <code>Look in:</code> select <code>Name</code>. The default <code>Description and Name</code> sometimes returns too many possibilities
-# We are searching for <code>libnet-ldap-perl</code> so enter <code>ldap-perl</code> (or something similar; you can copy and paste from this document if you want) and click on <code>Search</code>
-# This should result in 6 possibilities. Select and Mark for Installation (by double clicking or checking and then selecting <code>Mark for Installation</code>) <code>libnet-ldap-perl</code>. You will see a pop up window <code>Mark additional required changes?</code> and you should always click <code>Mark</code> to accept the requirements.
-# Follow this basic procedure for all the packages listed below
-Here is the list of Ubuntu packages that need to be installed.
-# <code>apache2</code>
-# <code>curl</code>
-# <code>dvipng</code>
-# <code>gcc</code>
-# <code>git</code>
-# <code>libapache2-request-perl</code>
-# <code>libarray-utils-perl</code>
-# <code>libcrypt-ssleay-perl</code>
-# <code>libdatetime-perl</code>
-# <code>libdancer-perl</code>
-# <code>libdancer-plugin-database-perl</code>
-# <code>libdata-dump-perl</code>
-# <code>libdbd-mysql-perl</code>
-# <code>libemail-sender-perl</code>
-# <code>libexception-class-perl</code>
-# <code>libextutils-xsbuilder-perl</code>
-# <code>libfile-find-rule-perl-perl</code>
-# <code>libgd-perl</code>
-# <code>libhtml-scrubber-perl</code>
-# <code>libiterator-perl</code>
-# <code>libiterator-util-perl</code>
-# <code>libjson-perl</code>
-# <code>liblocale-maketext-lexicon-perl</code>
-# <code>libmime-tools-perl</code>
-# <code>libnet-ip-perl</code>
-# <code>libnet-ldap-perl</code>
-# <code>libnet-oauth-perl</code>
-# <code>libossp-uuid-perl</code>
-# <code>libpadwalker-perl</code>
-# <code>libpath-class-perl</code>
-# <code>libphp-serialization-perl</code>
-# <code>libpod-wsdl-perl</code>
-# <code>libsoap-lite-perl</code>
-# <code>libsql-abstract-perl</code>
-# <code>libstring-shellquote-perl</code>
-# <code>libtemplate-perl</code>
-# <code>libtext-csv-perl</code>
-# <code>libtimedate-perl</code>
-# <code>libuuid-tiny-perl</code>
-# <code>libxml-parser-easytree-perl</code>
-# <code>libxml-parser-perl</code>
-# <code>libxml-writer-perl</code>
-# <code>make</code>
-# <code>mysql-server</code>
-# <code>netpbm</code>
-# <code>openssh-server</code>
-# <code>preview-latex-style</code>
-# <code>texlive</code>
-# <code>texlive-latex-extra</code>
-# <code>unzip</code>
-When I do this I see on the bottom of <code>Synaptic Package Manager</code> window <code>82 to install/upgrade</code>, <code>1 to remove</code>. Your numbers may differ slightly.
-Now click <code>Apply</code> and <code>Apply</code> again to confirm the changes.
-That completes the set up of your base Ubuntu system. You can quit the <code>Synaptic Package Manager</code>.
-'''If you would prefer to install all of these packages in one fell swoop''', first become root:
- $ sudo su
- [sudo] password for wwadmin: <wwadmin password>
-and then run the command
- # apt install apache2 curl dvipng gcc git libapache2-request-perl \
- libarray-utils-perl libcrypt-ssleay-perl libdancer-perl libdancer-plugin-database-perl \
- libdata-dump-perl libdatetime-perl libdbd-mysql-perl libemail-sender-perl \
- libexception-class-perl libextutils-xsbuilder-perl libfile-find-rule-perl-perl \
- libgd-perl libhtml-scrubber-perl libiterator-perl libiterator-util-perl libjson-perl \
- liblocale-maketext-lexicon-perl libmime-tools-perl libnet-ip-perl libnet-ldap-perl \
- libnet-oauth-perl libossp-uuid-perl libpadwalker-perl libpath-class-perl \
- libphp-serialization-perl libpod-wsdl-perl \
- libsoap-lite-perl libsql-abstract-perl libstring-shellquote-perl libtemplate-perl \
- libtext-csv-perl libtimedate-perl libuuid-tiny-perl libxml-parser-easytree-perl \
- libxml-parser-perl libxml-writer-perl make mysql-server netpbm \
- openssh-server preview-latex-style texlive texlive-latex-extra unzip
-If prompted, you can always accept the default (hit <code>&lt;Enter&gt;</code>).  When the process finishes, enter
- # exit
-to return to a regular user.
-== Accessing Your Server Remotely ==
-At this point 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) but you may have to reboot your server for SSH access to take effect.
-You can do almost all (all if you are a unix expert) of the remaining installation from a remote location if you wish.
-== Editing Files ==
-You can use your favorite editor but we will give instructions assuming you are using the graphical editor <code>gedit</code>.  If you are editing files remotely, the terminal mode editor <code>nano</code> is available.
-== Installing Perl Modules ==
-We now have to install several additional Perl modules which unfortunately are not available from the Debian package system.
-=== Testing Perl Modules  ===
-To test if a Perl module is installed and working on your system, issue the following command, replacing <code>Module</code> with the name of the module:
- $ perl -MModule -e 'print "installed!\n"'
-If the module is installed you will see <code>installed!</code>. If not you will see at lot of gibberish.  E.g. at this stage in our installation process <code>CPAN</code> is installed and <code>MXML::Parser::EasyTree</code> 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 ...
-You can check the version of an installed module by the following command, replacing <code>Module</code> with the name of the module:
-  perl -MModule -e 'print "$Module::VERSION\n"'
-For example for the GD.pm module
-  perl -MGD -e 'print "$GD::VERSION\n"'
-=== Installing Additional Perl Modules from CPAN ===
-Be aware that in rare cases you might have to
-as root run
- $ sudo su
- [sudo] password for wwadmin: <wwadmin 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.
- $ sudo su
- [sudo] password for wwadmin: <wwadmin password>
- # perl -MCPAN -e shell
-Since this is the first time you are using CPAN it will ask you <code>Would you like me to configure as much as possible automatically?</code>
-Answer <code>Yes</code> (the default) and that should be it. If you are asked for a method to use, choose <code>sudo</code>.  If you are asked
-choose some CPAN mirror sites, you can just answer <code>Yes</code> (the default).
-Now we update CPAN itself
- cpan> install Bundle::CPAN
-and always hit <code>&lt;Enter&gt;</code> to accept the defaults when prompted (e.g. when you see "Enter arithmetic or Perl expression: exit").  This can be a long process, 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 Statistics::R::IO
-and in case you are prompted accept all defaults by just hitting <code>&lt;Enter&gt;</code>.
-Note that with more than one module to install, we just list them after <code>install</code> separated by spaces.
-When you again see the
- cpan>
-prompt enter
- cpan> exit
- #
-== Apache 2 and mod_perl ==
-We enable the info module. Acting as <code>root</code> in a terminal window enter
- # a2enmod info
-Next we make a copy of the configuration files we will be editing for safekeeping.
- # cd /etc/apache2/mods-available
- # cp info.conf info.conf.bak1
- # cp status.conf status.conf.bak1
- # exit
- $
-Now we will edit configuration files <code>info.conf</code> and <code>status.conf</code> 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 <code>gedit</code>.  Note that you have to be root to edit these files. First we edit <code>info.conf</code>
- $ cd /etc/apache2/mods-available
- $ sudo gedit info.conf
- [sudo] password for wwadmin: <wwadmin password>
-I suggest you allow access to server information from e.g. your department domain. To do this uncomment (i.e. remove the <code>#</code> from)
- 	Require ip 192.0.2.0/24
-and then replace <code>192.0.2.0/24</code> by <code>.math.yourschool.edu</code>
-where of course you should edit <code>.math.yourschool.edu</code> appropriately.
-Then save the file and quit (<code>Save</code> and  <code>File</code>, <code>Quit</code>).
-Now we edit <code>status.conf</code>
- $ cd /etc/apache2/mods-available
- $ sudo gedit status.conf
- [sudo] password for wwadmin: <wwadmin password>
-Edit the
-  #Require ip 192.0.2.0/24
-line just as you did for <code>info.conf</code>.
-Then save the file and quit. And restart Apache so that the above changes take effect
- $ sudo apache2ctl restart
- password:<wwadmin password>
-Now we have to set your server's fully qualified domain name. Note that if your network was set up automatically via DHCP, your server's fully qualified domain name should already be set up. You can check by running the <code>hostname</code> commands below.
-Run the command
- sudo hostnamectl set-hostname webwork
- [sudo] password for wwadmin: <wwadmin password>
-where of course you should replace webwork by whatever your server's name is.
-You can check these settings by running the commands
- $ hostname --fqdn
-and
- $ hostname
-The first gives the server's fully qualified domain name (e.g. webwork.mydepartment.myschool.edu) and the second the server's name (e.g. webwork).
-Note that if your server can not find its fully qualified domain name, certain tools (such as the Synaptic Package Manager) may not start.
-Now restart Apache
- $ sudo apache2ctl graceful
- [sudo] password for wwadmin: <wwadmin password>
-or
- $ sudo service apache2 restart
- [sudo] password for wwadmin: <wwadmin password>
-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 '''Apache2 Ubuntu Default Page''' indicating that Apache is running.
-You can check Apache's status by connecting to
-"http://localhost/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://localhost/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 <code>Server Settings</code> you should see
- Server Version: Apache/2.4.29 (Ubuntu) mod_apreq2-20090110/2.8.0 mod_perl/2.0.10 Perl/v5.26.1
-(or something very similar) indicating that both <code>mod_apreq2</code> and <code>mod_perl</code> are installed.
-If you have problems now or in the future, a good first thing to do is to look at the Apache error log which is located at <code>/var/log/apache2/error.log</code>.  In the directory <code>/var/log/apache2/</code> you can "less" through the error log (<code>less error.log</code>), look at the last few entires (<code>tail error.log</code>) or run the command <code>tail -f error.log</code> which will display new error messages as they are appended to the file. Use
-<code>^C</code> to break out of <code>tail -f</code> .
-== Checking MySQL ==
-First check that MySQL is running by
- $ sudo mysql
- [sudo] password for wwadmin: <wwadmin password>
-You should see something very similar to
- Welcome to the MySQL monitor.  Commands end with ; or \g.
- Your MySQL connection id is 2
- Server version: 5.7.22-0ubuntu18.04.1 (Ubuntu)
- ...
- Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
-Enter <code>exit</code> to exit
- mysql> exit
- Bye
- $
-== Checking Apache ==
-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 '''Apache2 Ubuntu Default 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 if you have not yet done so (non secure telnet and FTP are not allowed but secure SSH and SFTP are).
-== MySQL Security and Performance Issues ==
-As initially set up, MySQL is an open system. There are anonymous accounts with full privileges for some databases and other issues. We will fix that now.  Run the command
- sudo mysql_secure_installation
- [sudo] password for wwadmin: <wwadmin password>
-You can setup the VALIDATE PASSWORD plugin if you wish. I chose not to.
-Next you will be asked to enter a
-<code>New password for the MySQL "root" user</code>. Enter your chosen MySQL <code>root</code> password. You have to enter a password but it will not be used. In Ubuntu systems running MySQL 5.7 (and later versions), the root MySQL user is set to authenticate using the auth_socket plugin by default rather than with a password.
-You almost certainly want to answer 'Y' to all questions '''except''' possibly for the first one which asks if you want to set up a VALIDATE PASSWORD plugin.
-Now test that all is well:
- $ sudo mysql
- [sudo] password for wwadmin: <wwadmin password>
-You should see
- Welcome to the MySQL monitor ...
- mysql>
-Now lets check the MySQL users.
-There are four accounts. To see the accounts, do the following
- mysql> SELECT user,authentication_string,plugin,host FROM mysql.user;
-You will see a table with four users (<code>root</code>, <code>mysql.session</code>, <code>mysql.sys</code> and <code>debian-sys-maint</code>).
-You should see that one of the four users has a valid password (which will be displayed in encrypted form) and <code>root</code> is authenticated by a socket.  You can ignore the <code>mysql.session</code> and <code>mysql.sys</code> users.
-Now exit MySQL
- mysql> exit
- Bye
- $
-This last step is optional since currently most of WeBWorK's MySQL tables are now creating using the MyISAM engine (by default -- this can be changed in the config files) rather than the MySQL default engine. Now we change MySQL's default engine.  The default engine is InnoDB as of MySQL 5.5.5 (MyISAM before 5.5.5) but (at least on some hardware) InnoDB seems to be 50-100 times slower than MyISAM. So we will change the default MySQL engine from InnoDB to MyISAM. Note  that this change only applies to new tables, tables already constructed will continue to use InnoDB.  But we haven't created any WeBWorK tables so we don't have to change the engine for any existing tables.  '''Note:''' There is a report of a problem using MyISAM by a French speaking professor who changed MySQL's default character set to utf8 (see http://webwork.maa.org/moodle/mod/forum/discuss.php?d=3174). If you change MySQL's default character set, you should research  what is the best engine to use.
-To change the default MySQL engine from InnoDB to MyISAM do the following:
- $ cd /etc/mysql/mysql.conf.d
- $ sudo cp mysqld.cnf mysqld.cnf.bak1
- [sudo] password for wwadmin: <wwadmin password>
- $ sudo gedit mysqld.cnf
-Search for <code>[mysqld]</code> and under "Basic Settings" above the "user = mysql" line add the line
- default-storage-engine = myisam
-Then save the file and quit. Restart Mysql
- $ sudo /etc/init.d/mysql restart
- [sudo] password for wwadmin: <wwadmin password>
-or
- $ sudo service mysql restart
- [sudo] password for wwadmin: <wwadmin password>
-and log into mysql
- $ sudo mysql
- [sudo] password for wwadmin: <wwadmin password>
-You will see
- Welcome to the MySQL monitor ...
- mysql>
-If you show MySQL engines, you should see that MyISAM is listed as the default engine.
- mysql> SHOW ENGINES\G
-Now exit
- mysql> exit
- Bye
- $
-==Remove Guest Account Login==
-Ubuntu allows a guest login which we will remove.  In a terminal window run the commands
- $ cd /usr/share/lightdm/lightdm.conf.d
- $ sudo cp 50-ubuntu.conf 50-ubuntu.conf.bak1
- [sudo] password for wwadmin: <wwadmin password>
- $ sudo gedit 50-ubuntu.conf
-At the end (below the last line) add the new line
- allow-guest=false
-Then save the file and quit.  You have to reboot your server for this to take effect.
-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 Git to download WeBWorK from Github. 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 (<code>^C</code>) them from this document and paste (<code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code>) them in a terminal window
- $ cd
- $ cd downloads
- $ git clone git://github.com/openwebwork/webwork2.git
- $ git clone git://github.com/openwebwork/pg.git
- $ git clone git://github.com/openwebwork/webwork-open-problem-library.git
- $ git clone git://github.com/mathjax/MathJax.git
-'''Important Note'''.  The above commands retrieve the master branch which gives the latest stable release of the software package (webwork2, pg, etc) with bug fixes.  If a stable release newer than 2.13 exists, that will be downloaded and these instructions may be a little out of date.  So it is a good idea to check before downloading. The best way to do that is to look at https://github.com/openwebwork/webwork2/blob/master/VERSION and https://github.com/openwebwork/pg/blob/master/VERSION.
-The first and second download gives you the latest released versions.
-The third download contains the WeBWorK Open Problem Library (OPL) which is the new name for the original National Problem Library (NPL). The NPL has been renamed to reflect its growing international content. Your system will be loaded with many thousands of WeBWorK problems (over 30,000 currently).
-The fourth download is MathJax which is one of several options WeBWorK has to display mathematics online.
-The main information page about WebWork downloads is available at http://webwork.maa.org/wiki/Category:Release_Notes
-The main information page about the OPL is available at http://webwork.maa.org/wiki/Open_Problem_Library
-The main information page about MathJax is available at http://www.mathjax.org/
-==Installing WeBWorK==
-'''Note the the instructions below assume you are installing WeBWorK from scratch.  If you are just upgrading WeBWorK, especially if you already have existing WeBWorK courses, see [[Upgrading WeBWorK]].'''
-=== Move the System into the Required Directories ===
-As <code>root</code> create a <code>webwork</code> directory under <code>/opt</code>, change the ownership of the <code>webwork</code> directory to <code>wwwadmin</code>  and move directories there.
- $ cd
- $ cd downloads
- $ sudo mkdir /opt/webwork
- <wwadmin password>
- $ sudo chown wwadmin:wwadmin /opt/webwork
- $ mv webwork2 /opt/webwork/
- $ mv pg /opt/webwork/
-Move the mathjax directory to its proper location
- $ mv MathJax /opt/webwork/
-Now create the <code>courses</code> and <code>libraries</code> directories under <code>webwork</code> and copy and move content there
- $ mkdir /opt/webwork/courses
- $ mkdir /opt/webwork/libraries
- $ mv webwork-open-problem-library /opt/webwork/libraries/
- $ cd /opt/webwork/webwork2/courses.dist
- $ cp *.lst /opt/webwork/courses/
- $ rsync -a modelCourse /opt/webwork/courses/
-=== Setting Permissions ===
-The PG installation directory and files should be owned by <code>wwadmin</code> and not writable by other users:
- $ cd /opt/webwork/pg
- $ chmod -R u+rwX,go+rX .
-Most WeBWorK directories and files should also be owned by <code>wwadmin</code> and not writable by other users:
- $ cd /opt/webwork/webwork2
- $ chmod -R u+rwX,go+rX .
-Certain data directories need to be writable by the web server. These are <code>DATA</code>, <code>courses</code>, <code>htdocs/tmp</code>, <code>logs</code>, and <code>tmp</code>. 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 <code>wwdata</code>, containing both the WeBWorK administrators and the web server. Run the commands
- $ sudo addgroup wwdata
- <wwadmin password>
- $ sudo adduser wwadmin wwdata
-If there are other users who will also be administering WeBWorK files,
-now is a good time to add them.  To do this
-# Open <code>Show Applications</code>, type <code>Users</code> and open <code>Users</code>
-# Click the "Unlock" icon and enter the  <wwadmin password>
-# Click the "Add User..." button and create the new account
-# And remember to add the new account to the <code>wwdata</code> group as above.
-Now add the Apache2 webserver (which runs as <code>www-data</code>) to the <code>wwdata</code>
-group:
- $ sudo adduser www-data wwdata
-You can check that this succeeded in a terminal window by entering
- $ id wwadmin
-and then you should see <code>wwdata</code> listed under groups.  Also
- $ id www-data
-should show wwdata listed under groups.  Now we make the WeBWorK directories that need to be writable by the web server have <code>wwdata</code> 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.
- $ sudo su
- [sudo] password for wwadmin: <wwadmin password>
- # cd /opt/webwork/webwork2/
- # chgrp -R wwdata DATA ../courses htdocs/tmp htdocs/applets logs tmp /opt/webwork/pg/lib/chromatic
- # chmod -R g+w DATA ../courses htdocs/tmp htdocs/applets logs tmp /opt/webwork/pg/lib/chromatic
- # find DATA/ ../courses/ htdocs/tmp logs/ tmp/ -type d -a -exec chmod g+s {} \;
- # exit
- $
-=== Compile color.c ===
- $ cd /opt/webwork/pg/lib/chromatic
- $ gcc color.c -o color
-You may see some warning messages which you can safely ignore.
-== Configuring the Shell ==
-To make working with WeBWorK easier, there are a couple of changes you can make to your shell environment.
-Add the WeBWorK <code>bin</code> directory to your path. This will allow you to run WeBWorK command-line utilities without typing the full path to the utility. Goto your home directory and backup your <code>.bashrc</code> file
- $ cd
- $ cp .bashrc .bashrc.bak1
-Now edit <code>.bashrc</code>
- $ gedit .bashrc
-After the last line add the three lines:
- export PATH=$PATH:/opt/webwork/webwork2/bin
- export WEBWORK_ROOT=/opt/webwork/webwork2
- export PG_ROOT=/opt/webwork/pg
-Then save the file and Quit.
-Close your Terminal Window and open a new one so the above changes
-take effect. You can check that they have by
- $ echo $PATH
- $ echo $WEBWORK_ROOT
- $ echo $PG_ROOT
-== Checking Module Dependencies ==
-WeBWorK includes a script called <code>check_modules.pl</code> (in the directory <code>/opt/webwork/webwork2/bin</code>) that verifies that the needed programs and Perl modules are installed on your system. Run this script to make sure you have installed the required programs and Perl modules.
- $ check_modules.pl apache2
-Scroll up and look through the listing.  It should find everything.  If something is missing (flagged by <code>**</code>), look back through these instructions to find where it should have been installed and install it.  '''NOTE:'''  If you see
-"** Mail::Sender not found in @INC" you can ignore it as "Mail::Sender" has been replaced by "EMail::Sender" but
-check_modules.pl has not been properly updated.
-You may see some warning messages like
- Prototype mismatch: sub main::from_json: none vs ($@) at (eval 188) line 2.
- Prototype mismatch: sub main::to_json: none vs ($@) at (eval 188) line 2.
-This seems to be a known bug in libjson-perl and can be safely ignored.
-Now we check that all necessary LaTeX packages have been installed.  Run the commands
- $ cd
- $ pdflatex /opt/webwork/webwork2/bin/check_latex.tex
-and look for missing packages.
-== Configuring WeBWorK ==
-=== Making Copies of the Distribution Configuration Files ===
-Before configuring the system, you must make local copies of the <code>site.conf</code> and <code>localOverrides.conf</code> configuration files, located in <code>/opt/webwork/webwork2/conf/</code> .
- $ cd /opt/webwork/webwork2/conf
- $ cp site.conf.dist site.conf
- $ cp localOverrides.conf.dist localOverrides.conf
-=== System Configuration ===
-Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and  <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>.  These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file.  An instructor can only edit the <code>course.conf</code> file herself (for her own course) if she has "admin" privilege which by default instructors do not have. But most things instructors may want to customize and many others (language, timezone, permissions, display modes, email, ...) can be set using the Course Configuration page from within the course and such setting override those in the configuration files.
-Actually there are three main configuration files, <code>site.conf</code>,  <code>defaults.config</code> and <code>localOverrides.conf</code>.  The reason there are three configuration files is to make upgrading WeBWorK easier.
-* <code>site.conf</code>: This file contains global variables which are required for basic configuration.  It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.
-* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK.  Do not edit defaults.config. It will be overridden next time you upgrade.
-* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.
-There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options.
-==== Edit the site.conf file  ====
-Now edit <code>site.conf</code>
- $ cd /opt/webwork/webwork2/conf
- $ gedit site.conf
-First we have to add information about the Apache2 server setup.
-Search for <code>server_root_url</code> and edit the line so that it reads:
- $server_root_url   = "http://yourserver.yourschool.edu";
-where of course you should edit <code>yourserver.yourschool.edu</code> appropriately.  '''If you are running a secure server (i.e., using ssl), the url should start with https'''
-but you should wait to make that change until after WeBWorK is up and running and you set up ssl.
-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 unused password we set when securing MySQL.
-Search for <code>database_password</code> and replace the line
- $database_password = "passwordRW";
-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 <code>localhost</code>.  IMPORTANT: Our instructions above did not install an SMTP server so you will have to install and configure 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 <code>From</code> address on the mail message).  Edit the lines
- $mail{smtpServer} = '';  # e.g. 'mail.yourschool.edu' or 'localhost'
- $mail{smtpSender} = '';  # e.g.  'webwork@yourserver.yourschool.edu'
-entering the appropriate information. '''Be sure to use single quotes and NOT double quotes around email addresses otherwise Perl will treat @ as an array variabe.'''
-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 <code>DateTime::TimeZone::America::New_York</code> and you should enter  <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting timezones and formatting dates.
-Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.
-Then save the file and Quit.
-==== The defaults.config file  ====
-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), in <code>defaults.config</code>, you will see the lines
- $mail{allowedRecipients}     = [
-    #'prof1@yourserver.yourdomain.edu',
-    #'prof2@yourserver.yourdomain.edu',
- ];
-But we are not supposed to edit the <code>defaults.config</code> file, so if we want to do this, we will copy this to <code>localOverrides.conf</code> and edit it appropriately. Note that we should move this setting to the <code>site.conf</code> file.
-==== Edit the localOverrides.conf file  ====
- $ cd /opt/webwork/webwork2/conf
- $ gedit localOverrides.conf
-As we said above,
-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), in <code>localoverrides.config</code>, add and then edit the lines
- $mail{allowedRecipients}     = [
-    #'prof1@yourserver.yourdomain.edu',
-    #'prof2@yourserver.yourdomain.edu',
- ];
-removing the <code>#</code> and using 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 (which you find in the course directory) to the addresses of professors of each course. Note that the settings in course.conf override the settings in site.conf, default.conf and localOverrides.conf so if in addition you want e.g. the WeBWorK administrators to receive copies, you have to add them as well.
-Then save the file and Quit.
-After you have used WeBWorK for awhile, you may want to change the default header files in <code>defaults.config</code>. Search for <code>$webworkFiles{screenSnippets}{setHeader}</code> and <code>$webworkFiles{hardcopySnippets}{setHeader}</code> in <code>localOverrides.config</code>.  Settings in the conf and config files affect all WeBWorK courses. You can override any setting in these conf and config files for an individual course by putting the local setting in <code>course.conf</code>.
-Also now there are several versions of the classlist editor, homeworkset editor, library browser and pgproblem editor.  Which ones are available in a course is determined by the settings for  <code>%showeditors</code> in localOverrides.conf.  As above, if you want to customize what is available for an individual course (e.g. one professor may want to try out the new editors and others may not), copy the <code>%showeditors</code> structure to <code>course.conf</code> and then edit it to make available the desired editors.
-=== Set up the webwork database  ===
-WeBWorK uses a single database, called <code>webwork</code>, for all courses. We will create the <code>webwork</code> database now.
-To do this do the following ('''before you just copy, paste and hit <code>&lt;Enter&gt;</code>''' notice that you have to replace <code>database_password</code> with the password you set when editing <code>site.conf</code> above):
- $ sudo mysql
- [sudo] password for wwadmin: <wwadmin password>
- mysql> CREATE DATABASE webwork;
- mysql> CREATE USER 'webworkWrite'@'localhost' IDENTIFIED BY 'database_password';
- mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, LOCK TABLES ON webwork.* TO 'webworkWrite'@'localhost';
- mysql> exit
- Bye
- $
-where as we said replace <code>database_password</code> with the password you set when editing <code>site.conf</code> above.
-=== MathJax ===
-General information on MathJax including installation instructions can be found at http://www.mathjax.org/.  MathJax is already installed in the location <code>/opt/webwork/MathJax</code> and a link (called <code>mathjax</code>) to this directory is placed in <code>/opt/webwork/webwork2/htdocs/</code> .
-=== Configuring Apache ===
-WeBWorK ships with an Apache config file that needs to linked into your Apache configuration process. The file is named <code>webwork.apache2.4-config.dist</code> and located in the <code>conf</code> directory. First, copy the file to <code>webwork.apache2-config</code>:
- $ cd /opt/webwork/webwork2/conf
- $ cp webwork.apache2.4-config.dist webwork.apache2.4-config
-and now link it into your Apache configuration process
- $ sudo su
- [sudo] password for wwadmin: <wwadmin password>
- # cd /etc/apache2/conf-enabled
- # ln -s /opt/webwork/webwork2/conf/webwork.apache2.4-config webwork.conf
-The default multi-processing module (MPM) for Apache is the event module but WeBWorK uses the prefork module. So we disable the event module and enable the prefork module.
- # a2dismod mpm_event
- # a2enmod mpm_prefork
-Next we will make a few changes to Apache's default configuration. We need to edit two files and we will
-save copies of the original files.
- # cd /etc/apache2/
- # cp apache2.conf apache2.conf.bak1
- # exit
- $ cd /etc/apache2/
- $ sudo gedit apache2.conf
-Search for the line
- Timeout 300
-and replace it by
- Timeout 1200
-Then save the file and quit.
- $ sudo su
- [sudo] password for wwadmin: <wwadmin password>
- # cd /etc/apache2/mods-available/
- # cp mpm_prefork.conf mpm_prefork.conf.bak1
- # exit
- $ cd /etc/apache2/mods-available/
- $ sudo gedit mpm_prefork.conf
-Search for the lines
-     MaxRequestWorkers        150
-     MaxConnectionsPerChild   0
-Which occur under <code><IfModule mpm_prefork_module></code> and replace them by
- # For WeBWorK a rough rule of thumb is 5 MaxRequestWorkers per 1 GB of memory
-       MaxRequestWorkers        5
-       MaxConnectionsPerChild   50
-where you should set <code>MaxRequestWorkers</code> depending on the amount of memory your server has using the above rule of thumb. Note that for
-very busy servers, you should observe you memory usage and adjust the above settings as necessary.  Also make sure MaxSpareServers is not set too high.
-Then save the file and quit.
-Finally we copy WeBWorK's icon file <code>favicon.ico</code> to Apache's <code>www</code> directory.
- $ sudo cp /opt/webwork/webwork2/htdocs/favicon.ico /var/www/html
- [sudo] password for wwadmin: <wwadmin password>
-Now stop and start Apache. We do it this way to make sure the MPM gets changed.
- $ sudo apache2ctl stop
- $ sudo apache2ctl start
-== Test your configuration ==
-# Test the <code>/webwork2</code> location by visiting <code>http://yourserver.yourschool.edu/webwork2</code>. You should see the WeBWorK home page with no courses listed.  Actually the directory <code>/opt/webwork/courses/</code> does contain the <code>modelCourse</code> but the <code>modelCourse</code> 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 <code>/opt/webwork/courses/modelCourse/</code> contains a file named <code>hide_directory</code> and so the <code>modelCourse</code> is not visible.
-# Test the <code>/webwork2_files</code> location by visiting <code>http://yourserver.yourschool.edu/webwork2_files</code>. You should see the "WeBWorK Placeholder Page".
-# You cannot test the <code>/webwork2_course_files</code> 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 <code>localOverrides.conf</code> caused me problems, another time it was a missing single quote). A quick way to check this is to do a <code>diff</code> between the edited and distributed versions and check that <code>diff</code> reports the changes you made and only those. Another thing is to look at the Apache error log which is located at <code>/var/log/apache2/error.log</code>.
- $ cd /etc/apache2/
- $ diff apache2.conf apache2.conf.bak1
- $ cd /opt/webwork/webwork2/conf/
- $ diff site.conf site.conf.dist
- $ diff localOverrides.conf localOverrides.conf.dist
- $ diff webwork.apache2.4-config webwork.apache2.4-config.dist
- $ less /var/log/apache2/error.log
-If something is wrong and you fix it, you will have to restart Apache for the changes to take effect
- $ sudo service apache2 restart
- [sudo] password for wwadmin: <wwadmin password>
-== Create the admin Course ==
-[[Course Administration]] gives information about creating courses.  Here we will give explicit instructions for doing this. (You may need to become root or use sudo to execute some of these commands.)
- $ newgrp wwdata
- $ umask 2
- $ cd /opt/webwork/courses
- $ /opt/webwork/webwork2/bin/addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin
-Make the course <code>admin</code> and its subdirectories owned by the Apache server.
- $ sudo chown -R www-data  admin
- [sudo] password for wwadmin: <wwadmin password>
- $ exit
-Now goto <code>http://yourserver.yourschool.edu/webwork2</code> and should see the WeBWorK home page with <code>Course Administration</code> listed at the top. Click on it and login with Username <code>admin</code> and Password <code>admin</code> .  This first thing you should do is register your new WeBWorK installation. It's quick and easy, just click on <code>Register</code>.  The next thing you should do is click on <code>User Settings</code> and change <code>admin</code> 's password to something more secure than <code>admin</code> .
-Unless you choose otherwise, users with <code>admin</code> privileges in the <code>admin</code> course (i.e. WeBWorK administrators) will automatically be added to new courses with <code>admin</code> privileges and the same password as in the  <code>admin</code> course. Initially the only such user is <code>admin</code> (hopefully you are not confused by the fact that the course <code>admin</code> has a user named  <code>admin</code>).  It's usually convenient make yourself a WeBWorK administrator. To do this (assuming you are logged in as <code>admin</code> to the <code>admin</code> course at <code>http://yourserver.yourschool.edu/webwork2/admin</code> )
-# Click on <code>Classlist Editor</code> in the left panel
-# Click the <code>Add</code> tag and click <code>Take Action!</code>
-# Enter the appropriate information (you can use your <code>Login Name</code> as the <code>Student ID</code> if you want and also you can leave the last three items blank) and click <code>Add Students</code>
-# Click on <code>Classlist Editor</code> in the left panel again
-# When you enter a new student, by default their <code>Student ID</code> is used as their password. We'll change this now.
-# Select yourself with a check mark and click the <code>Password</code> tag and click <code>Take Action!</code>. (Note as a safely mechanism you can not change the password for the user you are logged in as, currently <code>admin</code>, this way)
-# Enter the password and then click <code>Take Action!</code>
-# Finally give yourself <code>admin</code> privileges by selecting yourself with a check mark, clicking the <code>Edit</code> tag 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 <code>student</code> to <code>admin</code>
-# Then click <code>Take Action!</code>
-At some point you will probably want to hide the <code>admin</code> course so that it is not listed on the WeBWorK home page.  As we noted above the <code>modelCourse</code>, 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 <code>modelCourse</code> is very useful as a model (hence its name) for setting up other courses. The <code>admin</code> course is used for administering WeBWorK and even though regular users can not log into it (you did change the <code>admin</code> password,  didn't you!!), it a little bit cleaner and safer to hide it from prying eyes.
-To hide (or unhide) a course select <code>Hide Inactive courses</code> in the admin course and follow the directions. When hidden a course will not show up in the courses list on the WeBWorK home page. It will still appear in the Course Administration listing. If you do this you will still be able to access the <code>admin</code> course using the URL <code>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> .
-Now goto <code>http://yourserver.yourschool.edu/webwork2</code> and no course will be listed.
-== Checking for and Installing Hotfixes ==
-The following commands show you how to check for and install bug fixes. '''Important Note:''' These commands check and retrieve the master branch which gives the latest stable release of the software package (webwork2, pg, etc) with bug fixes.  If a stable release newer than 2.13 exists for webwork2 and/or pg, that will be checked and retrieved which is probably not what you want.  Please check before updating. The best way to do that is to look at https://github.com/openwebwork/webwork2/blob/master/VERSION and https://github.com/openwebwork/pg/blob/master/VERSION.
-To check if there are bug fixes, do the following.
-===Updating the webwork2 code===
-First we check for updates to the webwork2 code:
- cd /opt/webwork/webwork2/
- git remote show origin
-This will print several lines of data, but the last line will tell you if your copy is up to date or out of date. If it is out of date, run
- git pull origin
-and restart apache2.
-===Updating the pg code===
-Now check for updates to the pg code:
- cd /opt/webwork/pg/
- git remote show origin
-This will print several lines of data, but the last line will tell you if your copy is up to date or out of date. If it is out of date, run
- git pull origin
-and restart apache2.
-===Restart apache2===
-'''Important:''' After updating either webwork2 or pg, you have to restart apache2
- $ sudo apache2ctl restart
- password:<wwadmin password>
-===Updating the OPL===
-The following assumes you have already installed the OPL. For that see [[#Install the Open Problem Library]] below.
-Now check for updates to the Open Problem Library:
- cd /opt/webwork/libraries/webwork-open-problem-library
- git remote show origin
-This will print several lines of data, but the last line will tell you if your copy is up to date or out of date. If it is out of date, run
- git pull origin
-Then rerun the <code>OPL-update</code> script. Updating the OPL is pretty much risk free since changes usually involve only a relatively small
-number of individual problems and the vast majority of problems remain unchanged. Updating the OPL does not require restarting apache2.
- $ OPL-update
-===Updating MathJax===
- cd /opt/webwork/MathJax/
- git remote show origin
-This will print several lines of data, but the last line will tell you if your copy is up to date or out of date. If it is out of date, run
- git pull origin
-Updating MathJax is usually very safe and does not require restarting apache2.
-== Starting and Stopping Apache, MySQL and the GNOME desktop GUI ==
-If you make changes to the system, you will have to restart <code>apache2</code> before the changes take effect. On rare occasions you may need to restart <code>MySQL</code>.
-=== Starting and Stopping Apache ===
-You have to run these commands as <code>root</code>.
-To start or restart (i.e. stop and then start) the <code>apache2</code> webserver run the command
- $ sudo apache2ctl graceful
- [sudo] password for wwadmin: <wwadmin password>
-You can also start <code>apache2</code> by
- $ sudo apache2ctl start
- [sudo] password for wwadmin: <wwadmin password>
-and restart it with
- $ sudo apache2ctl restart
- [sudo] password for wwadmin: <wwadmin password>
-<code>restart</code> is less graceful but more powerful than <code>graceful</code>.  Sometimes <code>graceful</code> fails to kill all <code>apache2</code> child processes.
-To stop the Apache webserver run the command
- $ sudo apache2ctl stop
- [sudo] password for wwadmin: <wwadmin password>
-Stopping and then starting Apache should definitely kill all <code>apache2</code> child processes.
-You can also start or stop apache2 by using the <code>init.d</code> script <code>apache2</code>.  Run
- $ sudo /etc/init.d/apache2
- [sudo] password for wwadmin: <wwadmin password>
-or equivalently
- $ sudo service apache2
- [sudo] password for wwadmin: <wwadmin password>
-and you will get a list of allowed commands (<code>start</code>, <code>stop</code>, <code>restart</code>, etc).
-=== Starting and Stopping MySQL ===
-You have to run these commands as <code>root</code>.
-To start the <code>MySQL</code> server run the command
- $ sudo /etc/init.d/mysql start
- password:<wwadmin password>
-To stop the <code>MySQL</code> server run the command
- $ sudo /etc/init.d/mysql stop
- [sudo] password for wwadmin: <wwadmin password>
-To restart the <code>MySQL</code> server run the command
- $ sudo /etc/init.d/mysql restart
- [sudo] password for wwadmin: <wwadmin password>
-Equivalently you can use the command
- $ sudo sudo service mysql
-followed by start, stop, restart,etc.  Just running the above alone will
-display a list of allowed commands.
-=== Starting and stopping the GNOME desktop GUI ===
-The GNOME desktop is automatically started when the system boots.
-To stop <code>GNOME</code> so that you only have a standard terminal window run the following in a standard terminal window
- $ sudo /etc/init.d/lightdm stop
- [sudo] password for wwadmin: <wwadmin password>
-After doing this, if you need to use the server for terminal input, type <code>&lt;Ctrl&gt;&lt;Alt&gt;&lt;F1&gt;</code> to get a command line terminal.
-If you stopped <code>GNOME</code> and want to restart it run the following in a standard terminal window
- $ sudo /etc/init.d/lightdm start
- [sudo] password for wwadmin: <wwadmin password>
-==Install the WeBWorK Problem Libraries ==
-Before we create a real course we will install the WeBWorK Problem Libraries.
-===Install the Open Problem Library ===
-The <code>Open 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 load a database for searching it.
-Run the <code>OPL-update</code> script.
- $ OPL-update
-This has to convert a lot of data for over 35,000 problems 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 easy, see [[#Updating the OPL|Updating the OPL]].  Note that this is something you should do fairly often so that your library is up to date with
-new problems and bug fixes for old ones.
-Finally we put a link to the Open Problem Library in the modelCourse so that when we create courses copying templates from the modelCourse, the OPL will be available.
- $ cd /opt/webwork/courses/modelCourse/templates/
- $ ln -s /opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary Library
-===Set up the access to the Contrib directory ===
-The <code>Contrib</code> directory contains contributions to the OPL that may not have been formally accepted into the main collection of OPL problems.  This may be because the contribution is recent and has not yet been reviewed or because the problems are not properly tagged as is the case with the CAPA problem collection. It also contains the original versions of problems that have been accepted into the OPL (the idea being that the original authors maintain control of problems in the <code>Contrib</code> directory but problems in the OPL are controled by the editors).  This step creates a button in the Library Browser which gives a direct link to the <code>Contrib</code> directory.
-We need to edit <code>localOverrides.conf</code>.
- $ cd /opt/webwork/webwork2/conf
- $ gedit localOverrides.conf
-Search for <code>courseFiles{problibs}</code> and under the line
-       Library =&gt; "OPL Directory",
-add the line
-       ContribDir =&gt; "Contrib",
-Then save the file and quit.
-We next put a link to the Contrib directory in the <code>modelCourse</code> so that when we create courses copying templates from the <code>modelCourse</code>, the Contrib directory will be available.
- $ cd /opt/webwork/courses/modelCourse/templates/
- $ ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib ContribDir
-If you just want to do this for individual courses, do the following. Note we don't have any individual courses yet. But for example after creating <code>myTestCourse</code> below, to set up access to the <code>Contrib</code> directory from <code>myTestCourse</code>, do the following
- $ cd /opt/webwork/courses/myTestCourse/templates/
- $ sudo $ ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib ContribDir
- [sudo] password for wwadmin: <wwadmin password>
-===Set up the Rochester and Union Libraries ===
-This step is optional. It creates buttons in the Library Browser which give direct links to the Rochester and Union libraries. If you don't do this, you can find these libraries and others under the <code>OPL Directory</code> button.
-First we need to edit <code>localOverrides.conf</code> one last time
- $ cd /opt/webwork/webwork2/conf
- $ gedit localOverrides.conf
-Search for <code>courseFiles{problibs}</code> and scroll down several lines to the lines
- #       rochesterLibrary =&gt; "Rochester",
- # 	unionLibrary     =&gt; "Union",
-Uncomment these lines (i.e. remove the <code>#</code>) so they become
-       rochesterLibrary =&gt; "Rochester",
-       unionLibrary     =&gt; "Union",
-Then save the file and quit.
-We next put links to the Rochester and Union Libraries in the <code>modelCourse</code> so that when we create courses copying templates from the <code>modelCourse</code>, these libraries will be available. Skip this step if you usually only want to use Open Problem Library.  Note that the Rochester, Union and other libraries are contained in the OPen Problem Library and are accessible from there under the <code>OPL Directory</code> button in the Library Browser. This step simply creates buttons in the Library Browser so that you can access the Rochester and Union libraries directly.
- $ cd /opt/webwork/courses/modelCourse/templates/
- $ ln -s /opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary/Union unionLibrary
- $ ln -s /opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary/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/webwork-open-problem-library/OpenProblemLibrary/</code> you might find other libraries that are not yet listed in <code>global.conf</code> and these can be added in the same way as the <code>Rochester and </code><code>Union</code> libraries.   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>
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code>'uva-statLibrary'      => "UVA-Stat",</code> <br>
-It's easier to just avoid such names.
-===Install and Set Up the CAPA Library ===
-This step is optional. It installs and sets up [[CAPA Physics Problems|the CAPA Library]], which is a library of physics problems.
-'''Note:''' We are in the process of integrating the CAPA problems into the main distribution so some of the details below may change.
-Move the CAPA graphics files to the required locations and set the group.
- $ cd /opt/webwork/libraries/webwork-open-problem-library/Contrib/CAPA
- $ mv CAPA_Graphics /opt/webwork/webwork2/htdocs/
- $ sudo chgrp -R wwdata /opt/webwork/webwork2/htdocs/CAPA_Graphics
-   [sudo] password for wwadmin: <wwadmin password>
- $ sudo chmod -R g+w /opt/webwork/webwork2/htdocs/CAPA_Graphics
-We need to edit <code>localOverrides.conf</code> again
- $ cd /opt/webwork/webwork2/conf
- $ gedit localOverrides.conf
-Search for <code>courseFiles{problibs}</code> and scroll down several lines to the line
- #      capaLibrary      => "CAPA",
-Uncomment this line (i.e. remove the <code>#</code>) so it becomes
-       capaLibrary      => "CAPA",
-Now search for the lines
- #$pg{specialPGEnvironmentVars}{CAPA_Tools}             = "$courseDirs{templates}/Contrib/CAPA/macros/CAPA_Tools/",
- #$pg{specialPGEnvironmentVars}{CAPA_MCTools}           = "$courseDirs{templates}/Contrib/CAPA/macros/CAPA_MCTools/",
- #$pg{specialPGEnvironmentVars}{CAPA_GraphicsDirectory} = "$courseDirs{templates}/Contrib/CAPA/CAPA_Graphics/",
- #push @{$pg{directories}{macrosPath}},
- #  "$courseDirs{templates}/Contrib/CAPA/macros/CAPA_Tools",
- #  "$courseDirs{templates}/Contrib/CAPA/macros/CAPA_MCTools";
-and replace these six lines by
- ################################################################################
- #Locations of CAPA resources. (Only necessary if you need to use converted CAPA problems.)
- ################################################################################
- $pg{specialPGEnvironmentVars}{CAPA_Tools}             = "$courseDirs{templates}/ContribDir/CAPA/macros/CAPA_Tools/",
- $pg{specialPGEnvironmentVars}{CAPA_MCTools}           = "$courseDirs{templates}/ContribDir/CAPA/macros/CAPA_MCTools/",
- $pg{specialPGEnvironmentVars}{CAPA_GraphicsDirectory} = "$webworkDirs{htdocs}/CAPA_Graphics/";
- $pg{specialPGEnvironmentVars}{CAPA_Graphics_URL}      = "$webworkURLs{htdocs}/CAPA_Graphics/";
-Then save the file and Quit.
-There is one final step that is needed. We have to put a link in the templates directory of every course that needs access to the CAPA Library.  If you want to have every course you create have access to the CAPA Library (unlikely unless you are in a physics department) put the link in the <code>modelCourse</code>
- $ cd /opt/webwork/courses/modelCourse/templates/
- $ ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib/CAPA/   capaLibrary
-More likely you just want to do this for individual courses. We don't have any yet. But for example after creating <code>myTestCourse</code> below, to set up access to the CAPA Library from <code>myTestCourse</code>, do the following
- $ cd /opt/webwork/courses/myTestCourse/templates/
- $ sudo ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib/CAPA/   capaLibrary
- [sudo] password for wwadmin: <wwadmin password>
-and do the analogous thing for every course that needs access to the CAPA Library.
-Then to gain access to the CAPA Library from the course, simply go to the  <code>Library Browser</code> and click on the  <code>CAPA</code> button.
-==Create Your First Actual Course ==
-Since we have edited <code>site.conf</code> and <code>localOverrides.conf</code> and these are critical files, it would be a good idea to run
- $ cd /opt/webwork/webwork2/conf
- $ diff site.conf site.conf.dist
- $ diff localOverrides.conf localOverrides.conf.dist
-and check that you haven't made any mistakes (e.g. by introducing an inadvertent line break, etc). If there are any mistakes, correct them. Remember that any time you change either of these files you must restart the Apache webserver in order for these changes to take effect.
-Since we have edited <code>global.conf</code> and haven't restarted Apache we do so now.
- $ sudo apache2ctl graceful
- password:<wwadmin password>
-Now log into the <code>admin</code> course ( <code>http://yourserver.yourschool.edu/webwork2/admin</code> or, if you have not hidden the admin course, click on <code>Course Administration</code> on WeBWorK's home page <code>http://yourserver.yourschool.edu/webwork2/</code> ) as yourself or <code>admin</code>   and
-# click on <code>Add Course</code>
-# For <code>Course ID</code> enter <code>myTestCourse</code>
-# For <code>Course Title</code> enter <code>My Test Course</code>
-# Enter your institution
-# Leave <code>Add WeBWorK administrators to new course</code> checked
-# Add an additional instructor if you wish
-# Copy templates from: <code>modelCourse</code> (the default action)
-# Select sql_single for the  database layout  (the default and only choice)
-# Click on <code>Add Course</code>
-# Click <code>Log into myTestCourse</code>
-and log in either as <code>admin</code> or yourself (if you added yourself as an additional instructor above).
-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>/var/log/apache2/error.log</code>.
-Click on <code>Hmwk Sets Editor</code> on the <code>Main Menu</code>. Then select <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.
-Continue looking at problems to see if everything is working properly.
-Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>.  The page is a little complicated because you are a professor (students see a very simple page) but you can just scroll to the bottom and click on <code>Generate hardcopy for selected users and selected sets</code>.  If you get an error (you shouldn't) 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).  If you want to preserve these tmp files,  set <code>$WeBWorK::ContentGenerator::Hardcopy::PreserveTempFiles</code>
-to 1 in the file <code>Constants.pm</code> in the directory <code>/opt/webwork/webwork2/lib/WeBWorK</code> and then restart Apache.  Remember to set this back to 0 after debugging.
-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>Open Problem Library </code> (actually it should already be selected so it will greyed out)
-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 <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 <code>Add</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.
-==Optional Configurations==
-'''Optional A''' stores WeBWorK's "temporary" files in a separate partition (or directory).
-'''Optional B''' installs and configures a lightweight webserver to serve static files.
-'''Optional C''' configures Apache so that access to WeBWorK will be through SSL.
-===Implement Optional A (wwtmp)===
-Now is the time to implement '''Optional A''' if you choose to do so.  Actually you can do this at any time and your active courses will continue to function seemingly without change.  The only change behind the scenes will be that temporary files will be stored in a different location. Note that if you want to use this option but did not create <code>wwtmp</code> as a separate partition, you first have to create the directory <code>/var/www/html/wwtmp</code> with the command
- sudo mkdir /var/www/html/wwtmp
- [sudo] password for wwadmin: <wwadmin password>
-All of WeBWorK's "temporary" files will be stored under <code>/var/www/html/wwtmp</code>.  These are mostly small files such as png images of equations, pdf files, etc that may be reused but if they are not present (e.g. if they get deleted) they will be seamlessly regenerated on the fly. There is no reason to back up such files and having them in a separate partition or directory means that it is easier and faster to back up other partitions and skip backing up unnecessary files. Even if you do not want to set up a separate partition for this, it is very convenient to at least set up a separate directory for these temporary files and we recommend that yo do so.
-First we set the group and permissions for the <code>wwtmp</code> directory
- $ sudo su
- [sudo] password for wwadmin: <wwadmin password>
- # cd /var/www/html
- # chown wwadmin wwtmp
- # chgrp wwdata wwtmp
- # chmod ug+w wwtmp
- # chmod g+s wwtmp
- # exit
- $
-Next we have to edit <code>localOverrides.conf</code> so that WeBWorK uses the new <code>wwtmp</code> directory.  Since we have a working WeBWorK system, first we make a backup copy of <code>localOverrides.conf</code>.
- $ cd /opt/webwork/webwork2/conf
- $ cp localOverrides.conf localOverrides.conf.bak1
- $ gedit localOverrides.conf
-Now edit <code>localOverrides.conf</code>.  Search for the line
- # Directory for temporary files
-and under that find the line
- # To implement, uncomment the following 6 lines:
-Then uncomment (i.e. remove the # symbol) from the 6 lines
- #$webworkDirs{htdocs_temp}  =  '/var/www/html/wwtmp';
- #$webworkURLs{htdocs_temp}   = '/wwtmp';
- #$webworkDirs{equationCache} = "$webworkDirs{htdocs_temp}/equations";
- #$webworkURLs{equationCache} = "$webworkURLs{htdocs_temp}/equations";
- #$courseDirs{html_temp}  =  "/var/www/html/wwtmp/$courseName";
- #$courseURLs{html_temp}   = "/wwtmp/$courseName";
-'''IMPORTANT NOTE'''. Apache 2.4 has changed the default location of the document root from <code>/var/www</code> to
-<code>/var/www/html</code> and we are in the process of updating the file <code>localOverrides.conf.dist</code> to reflect this.
-If your copy of this file does not have <code>/html</code> in the two lines above, then in addition to uncommenting the 6 lines you also have to add <code>/html</code> in two places.
-Then save the file and quit. If you look at the <code>wwtmp</code> directory you will find it empty but after you restart apache and then access some WeBWorK problems, you will find temporary directories and files in <code>wwtmp</code>.  Remember your have to restart apache for these changes to take effect.
-====Using Cron Jobs to remove temporary files====
-It is a good idea to clean out temporary files on a regular automatic schedule.  Also pdf copies of downloaded problem sets are saved in a temporary directory (<code>wwtmp/.../hardcopy</code>) so that they can be downloaded from the web.  But after the download, the pdf file remains and is visible from the web if one knows the URL. For this reason we recommend deleting all such files that are over one hour old.  Similarly we recommend deleting all png, gif, and html links under <code>wwtmp</code> that are over 30 days old. And finally every week we recommend deleting all equation images that are over 14 days old. The following cron jobs will accomplish this.  The first is run every 30 minutes, the next three twice a month and the last one weekly on Sunday morning.  These cron jobs should be run as root.  We use <code>crontab</code> to edit the <code>crontab</code> file:
- $ sudo su
- [sudo] password for wwadmin: <wwadmin password>
- # crontab -e
-Now add the lines
- WEBWORK_ROOT=/opt/webwork/webwork2
- */30 * * * *  find /var/www/html/wwtmp/*/hardcopy/*  -mmin +60  -name "*" -delete
-5 1,15 * *  find /var/www/html/wwtmp/*/gif/  -mtime +30  -name "*" -delete
-5 2,16 * *  find /var/www/html/wwtmp/*/png/  -mtime +30  -name "*" -delete
-5 3,17 * *  find /var/www/html/wwtmp/*/html/  -mtime +30  -name "*" -delete
-5 * * 0 /opt/webwork/webwork2/bin/remove_stale_images --delete --days 14
-and save the file and quit
- # exit
- $
-===Implement Optional B (lighttpd)===
-As is the case for '''Optional A''' you can implement '''Optional B''' at any time and your active courses will continue to function seemingly without change.  The only change behind the scenes will be that static images, pages and MathJax will be served by a light weight web server.
-First we install the light weight webserver <code>lighttpd</code>
-# Open the <code>Synaptic Package Manager</code> (select <code>Show Applications</code> and type <code>Synaptic</code> and click on the <code>Synaptic Package Manager</code> icon).   You will have to enter the <code>&lt;wwadmin password&gt;</code>. The <code>Synaptic Package Manager</code> window will open).
-# Select <code>Search</code>
-# Search for <code>lighttpd</code> and select it
-# In the pop up window <code>Mark additional required changes?</code> click <code>Mark</code> to accept the requirements.
-# Now click <code>Apply</code> and <code>Apply</code> again to confirm the changes.
-You can now quit the <code>Synaptic Package Manager</code>.
-Now we configure <code>lighttpd</code>.  First let's make a backup of the configuration file.
- $ cd /etc/lighttpd
- $ sudo cp lighttpd.conf lighttpd.conf.bak1
- [sudo] password for wwadmin: <wwadmin password>
-Now edit <code>lighttpd.conf</code>.
- $ sudo gedit lighttpd.conf
-Ubuntu has changed the default document root from <code>/var/www</code> to <code>/var/www/html</code>
-so we set this for lighttpd as well.  Find the line
- server.document-root        = "/var/www"
-and replace it by
- server.document-root        = "/var/www/html"
-Apache2 is listening on port 80 so we need an alternate port for lighttp to listen to. Standard alternate ports for this are usually 81, 8000, or 8080. 8080 is the only port that is listed as an official alternate at http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers .  Note that in rare cases an installation may block httpd requests to port 8080. If any of your students report that they can not see graphics, they will have to request that access to requests to port 8080 be allowed.
-Find the line
- server.port        = 80
-and replace it by
- server.port        = 8080
-Now we make a few more changed that allow MathJax to run under lighttpd.  In the section <code> server.modules = (</code>, under the line
-  #       "mod_rewrite",
-add the line
- "mod_setenv",
-Then below the closing parentheses and above the line
- server.document-root        = "/var/www/html"
-add the lines
- setenv.add-response-header = ( "Access-Control-Allow-Origin" => "*" )
- alias.url = ( "/webwork2_files" => "/opt/webwork/webwork2/htdocs/" )
-Then save the file and quit.
-Now restart lighttp
- $sudo /etc/init.d/lighttpd restart
-Note that you can just run <code>/etc/init.d/lighttpd</code> to get a list of all options.
-Now test your server by connecting to
-"http://localhost:8080/" and/or connecting to your
-server from a browser on a remote machine ("http://yourserver.yourschool.edu:8080/").  You should see the '''Apache2 Ubuntu Default Page''' indicating that lighttp is running.   Test the <code>/webwork2_files</code> location by visiting "http://localhost:8080/webwork2_files" and/or "http://yourserver.yourschool.edu:8080/webwork2_files</code>. You should see the "WeBWorK Placeholder Page".
-Next we configure WeBWorK to take advantage of lighttp.
-First let's make a backup copy of <code>localOverrides.conf </code> so that we can easily back out of these changes if necessary.
- $ cd /opt/webwork/webwork2/conf
- $ cp localOverrides.conf localOverrides.conf.bak2
-Now edit <code>localOverrides.conf</code>.  Note that while '''Optional B''' is independent of '''Optional A''', we assume most people implementing '''Optional B''' will have already implemented '''Optional A'''.  Therefore we give instructions for editing
-localOverrides.conf assuming that '''Optional A''' has been implemented. If this is not the case,  modify the instructions below accordingly.  Also replace <code>yourserver.yourschool.edu</code> with the correct address.
- $ gedit localOverrides.conf
-Find the line
- $webworkURLs{htdocs_temp}   = '/wwtmp'
-and replace it by
- #$webworkURLs{htdocs_temp}   = '/wwtmp';
- $webworkURLs{htdocs_temp}   = 'http://yourserver.yourschool.edu:8080/wwtmp';
-Find the line
- $courseURLs{html_temp}   = "/wwtmp/$courseName";
-and replace it by
- #$courseURLs{html_temp}   = "/wwtmp/$courseName";
- $courseURLs{html_temp}   = "http://yourserver.yourschool.edu:8080/wwtmp/$courseName";
-Under this line add the lines
- # Location of MathJax script, used for the MathJax display mode.
- $webworkURLs{MathJax}       = "http://yourserver.yourschool.edu:8080/webwork2_files/mathjax/MathJax.js?config=TeX-MML-AM_HTMLorMML-full";
-Then save the file and quit.
-Now restart apache and lighttp.
- $ sudo apache2ctl graceful
- password:<wwadmin password>
- $ sudo /etc/init.d/lighttpd restart
-To test things go to your test course <code>http://yourserver.yourschool.edu/webwork2/myTestCourse/</code>. Log into your course and view a problem with a graphic image (e.g. Problem 2 of the Demo set).  Right click on the typeset equation and click on Properties (or whatever is appropriate on your browser, e.g. copy image location) and check that the image is being served from port 8080 (something like <code>http://yourserver.yourschool.edu:8080/wwwtmp/equations/...</code>).  To test that MathJax is using lighttpd, view a problem with some typeset equations.  Right click on the equation and you should see the MathJax menu.  Next look at the source code for the page and in the source, search for mathjax.js.  You should see that this is being loaded from port 8080.
-===Disabling Optional B (lighttpd) for a single course===
-If your server is hosting courses from different institutions, you may find that you need to disable using lighttpd for a single course, e.g. because the institution blocks access to port 8080.  Actually since port 8080 is an "official" alternate httpd port, you should first try to get the network administrators at the institution to grant access to port 8080.  Failing this, you can disable using lighttpd and instead use apache for a single course by adding the following lines to the end of the course's <code>course.conf</code> file which is located in the top level directory for the course (usually  <code>/opt/webwork/courses/course_name</code>).  Note that using apache instead of lighttpd will put a slightly larger load on the server. Also note that you need "admin" level privileges to edit the <code>course.conf</code> file.  Instructors with only "professor" level privileges can not do this from within WeBWorK.
- # Do not use lightppd (port 8080) for this course
- $webworkURLs{htdocs_temp}   = '/wwtmp';
- $courseURLs{html_temp}   = "/wwtmp/$courseName";
- $webworkURLs{equationCache} = "$webworkURLs{htdocs_temp}/equations";
- $webworkURLs{MathJax}       = "$webworkURLs{htdocs}/mathjax/MathJax.js?config=TeX-MML-AM_HTMLorMML-full";
-===Implement Optional C (SSL)===
-'''Optional C''' configures apache so that access to WeBWorK will be through an encrypted Secure Sockets Layer (SSL) with an https: URL. Note that if you implemented '''Optional B''', the non encrypted lighttp server will be used for images, etc so we will also have to set up the lighttp server to run under SSL (see below).
-I cribbed these directions from several sources, the main one being
-https://www.digitalocean.com/community/tutorials/how-to-create-a-ssl-certificate-on-apache-for-ubuntu-14-04.
-First we have to obtain an official SSL certificate or generate a self-signed one which can be used for testing purposes. If students will be using your server, it is better to obtain an official SSL certificate since using a self-signed certificate with cause warning messages to be displayed when students connect to the server.
-====Obtain an Official SSL Certificate====
-Talk to the networking group on your campus about obtaining an official certificate.  You can find information on the net about certificate providers, e.g. http://www.sslshopper.com/certificate-authority-reviews.html .
-The certificate goes in <code>/etc/ssl/certs/</code> and the key file goes in <code>/etc/ssl/private/</code>.
-====Create a self-signed Certificate====
-We can create a key and certificate with the following command
- sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/ssl/private/apache.key -out /etc/ssl/certs/apache.crt
- [sudo] password for wwadmin: <wwadmin password>
-Enter the requested information. '''Important:''' when you are prompted for the <code>Common Name</code> enter your server's fully qualified domain name, something like  <code>yourserver.yourschool.edu</code>. You can leave most of the items blank.
-====Set up Apache to use SSL====
-First we enable the <code>mod_ssl</code> module
- $ sudo a2enmod ssl
- [sudo] password for wwadmin: <wwadmin password>
-Now we have to configure Apache to use SSL.
- $ cd /etc/apache2/sites-available/
- $ sudo cp default-ssl.conf default-ssl.conf.bak1
- [sudo] password for wwadmin: <wwadmin password>
- $ sudo gedit default-ssl.conf
-Our self-signed certificate and key files are named
-<code>apache.crt</code> and <code>apache.key</code>.  If you
-are using official files, put their names in the lines below. You will also have to edit the Certificate Chain, Certificate Authority and possibly other items.  Instructions for doing so are beyond the score of this document.
-Search for the lines
- SSLCertificateFile      /etc/ssl/certs/ssl-cert-snakeoil.pem
- SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
-and replace them by
- SSLCertificateFile      /etc/ssl/certs/apache.crt
- SSLCertificateKeyFile /etc/ssl/private/apache.key
-Then save the file and quit.  And enable <code>default-ssl.conf</code>
- sudo a2ensite default-ssl.conf
- [sudo] password for wwadmin: <wwadmin password>
-Finally we restart Apache
- sudo service apache2 restart
-and test things. Connect to https://yourserver.yourschool.edu/webwork2/myTestCourse
-You will be asked to accept the certificate. After you do so things should work just as before except that the connection will be via https except for images, etc if you using lighttp. In that case, viewing math expressions in image mode should work fine but using MathJax mode will fail.  We will fix that below.
-====Redirect http requests to https====
-Assuming that everything is working, the last thing we do is set things up so that requests to http://yourserver.yourschool.edu/webwork2/ are automatically redirected to https://yourserver.yourschool.edu/webwork2/.
- $ cd /etc/apache2/sites-available
- $ sudo cp 000-default.conf 000-default.conf.bak1
- [sudo] password for wwadmin: <wwadmin password>
- $ sudo gedit 000-default.conf
-In the
- <VirtualHost *:80>
-section just under the line
- DocumentRoot /var/www/html
-add the line
- Redirect permanent /webwork2 https://yourserver.yourschool.edu/webwork2
-where of course you should edit <code>yourserver.yourschool.edu</code> appropriately.
-Then save the file and quit.
-Restart Apache
- $ sudo service apache2 restart
-and try connecting to http://yourserver.yourschool.edu/webwork2/.  The real connection should be through  https://yourserver.yourschool.edu/webwork2/.
-====Check site.conf====
-This is important.  We have to check the value of $server_root_url in webwork2/conf/site.conf to make
-sure it uses https (so it should read e.g. https://yourserver.yourschool.edu). If
-you don't do this, your may run into strange problems in the Library Browser.
-To check, open the Library Browser, select a subject and then click on the chapter area. If you see a drop down list of chapters, things are working properly.
-Now we check and edit if necessary site.conf
- cd /opt/webwork/webwork2/conf
- gedit site.conf
-In the line
- $server_root_url = ...
-replace http by https if necessary. Then save the file, quit and restart apache
- sudo service apache2 restart
- [sudo] password for wwadmin: <wwadmin password>
-====Configure lighttpd to use SSL====
-For lighttpd you need to concatenate the key file and the certificate file into a single pem file by running the following command:
- $ sudo su
- [sudo] password for wwadmin: <wwadmin password>
- # cd /etc/ssl/private
- # cat apache.key ../certs/apache.crt > apache.pem
- # chmod 640 apache.pem
- # exit
- $
-If you are using official certificates,
-you will also have to edit the Certificate Chain, Certificate Authority and possibly other items. Instructions for doing so are beyond the score of this document. See e.g.
-http://redmine.lighttpd.net/projects/lighttpd/wiki/Docs_SSL
-Now edit <code>lighttpd.conf</code>.
- $ cd /etc/lighttpd
- $ sudo gedit lighttpd.conf
- [sudo] password for wwadmin: <wwadmin password>
-Under the line
- server.port                 = 8080
-add the following
- $SERVER["socket"] == "yourserver.yourschool.edu:8443" {
-   ssl.engine = "enable"
-   ssl.pemfile = "/etc/ssl/private/apache.pem"
- }
-Then save the file and quit.
-And restart lighttpd.
- $ sudo service lighttpd restart
- password:<wwadmin password>
-Finally we have to edit <code>localOverrides.conf</code>. We will assume you have already set up
-WeBWorK to use lighttpd as described in section [[#Implement Optional B (lighttpd)|Implement Optional B (lighttpd)]] above.  Assuming that, edit <code>localOverrides.conf</code>
- $ cd /opt/webwork/webwork2/conf
- $ gedit localOverrides.conf
-and replace all occurrences of 8080 by 8443 (one occurrence in three different lines). Then in these same three lines replace <code>http</code> by <code>https</code>  .
-Then save the file and restart apache
- $ sudo service apache2 restart
- password:<wwadmin password>
-and test that all is well by viewing a page with math expressions using MathJax mode.
-==Where to go From Here ==
-You should play around with <code>myTestCourse</code> e.g. click on <code>Library Browser</code> and browse the <code>Problem Library</code>.
-Look at [[A day in the life of a WeBWorK instructor]].
-Read [[Course Administration]] for more information about creating courses.
-Under Categories below click on Administrators to see a listing of other WeBWorK documentation for system administrators.
-[[Category:Administrators]]
-[[Category:Installation Manuals]]