Automated Install

Its been a while since my last post.  However the semester ended a couple of weeks ago and summer is here, which means that I can get more WeBWorK stuff done.  I'm going to put up a number of posts over the next several months.  A lot of what I will talk about was spurred by the recent code camp at Asheville, hosted by Western Carolina University.  You can read more about that here.

In this post I will be discussing recent strides that were made with the automated WeBWorK install script, ww_install, recently developed by Jason Aubrey.  I'll talk about what improvements we made and walk you through the installation process.

First off, ww_install is an automated installation script that is meant to get a vanilla WeBWorK server running on a fresh linux installation with as little fuss as possible.  It is ideal for those interested in trying WeBWorK out using a virtual machine, or doing development on multiple machines.  It is also good for initially setting up production machines.  Be aware, however, that most production machines will require manual configuration to set up things like SSL, or alternative authentication methods, or an email server, and so on.

This script was actually developed a little while ago by Jason Aubrey can be found at this github repository.  The current master branch on that repository supports the current WeBWorK master branch.  Neither it, nor the WeBWorK master branch, support Apache version 2.4, however.  (The 2.4 version comes standard with the newest editions of Ubuntu and Fedora.)  One of the main improvements we made to the install script during the code camp was to upgrade the installer to handle WeBWorK branches release/2.9 and develop, both of which do offer Apache 2.4 support.  (Another big improvement is a surprise!  Scroll to the end to see what it is...)

As of now the most recent branch of the installer, named ww3, supports the following distributions:

• Debian 7 - Wheezy
• Ubuntu 14.04 - Trusty Tahr
• CentOS 6 - <No Cute Name>
• Fedora 20 - Heisenburg

This reflects the general policy of WeBWorK moving forward.  We will concentrate on supporting the stable Debian version, the current CentOS version (and the equivalent RedHat), Ubuntu Long Term Support Versions, and (recent-ish) Fedora versions.    While we will not promise that things should work on the most recent Ubuntu or Fedora versions all the time, we do want people to let us know when something goes wrong.  Problems with those distributions will become problems for the officially supported distributions sooner rather than later. 

So lets get to the good stuff.  I'm going to walk you through the process of installing a WeBWorK server on a virtual machine.  Start by installing your favorite (supported) linux distribution...

In this example we will be installing Debian onto a VirtualBox virtual machine.   While you can install the full version of Debian, for virtual machines I recommend working with a smaller set of features.

Here I am only installing an SSH server and the standard system utilities.  I am not setting up a desktop environment.  You can run a desktop environment through the virtual machine but it slows things down.  I prefer to set up port forwarding so that I can use the host machine's terminal and browser, which are generally more responsive.  Next set up your initial user.  I recommend using wwadmin but you can use whatever user you like, even root.  Now I set up port forwarding.  

Here I am forwarding port 2222 to 22 on the guest machine, and 8888 to 80 on the guest machine so that I can access ssh and apache.  (Using this setup you can even access your WeBWorK installation remotely from another machine via ssh tunnelling.)  Once the installation is finished (it should be pretty quick with this few packages) start your virtual machine (you can even do so in headless mode using VBoxHeadless) and log into it using a terminal on the host machine with

ssh -p 2222 wwadmin@localhost

 Now you will want to get the installation script and run it.  Notice that we get the script from the ww3 branch, since that contains the latest changes.  (Eventually ww3 will be merged into master and you will just get that branch.)  

wget --no-check-config \ http://raw.github.com/aubreyja/ww_install/ww3/install_webwork.sh
sudo bash install_webwork.sh

 Of course, there is a corresponding curl command which you can use to get the file.  Now you wait while the script installs all of the necessary prerequisites.

• You will be asked to configure your mysqul server
• It may look like the script has stalled while installing perl modules.  This may be because the script is asking you a question but you can't see the prompt.  When in doubt ... just press Enter.

Eventually you will get through the installation process and the real fun begins.

The installation script will ask you a bunch of questions.  Things like:  "Where do you want to install WeBWorK?", "What is the URL of this site?", "Do you want to create a WeBWorK administrator account, or does one already exist?"  You should always read the prompts, but its also usually safe to just press enter.  There will always be a confirmation prompt and the default settings are usually pretty good.  The only time you will absolutely have to provide input is when you are creating the database.  

Here you will be asked for the mysql root user password, and to set the WeBWorK database password.  Note:  On some terminals the prompts can be cut off.  Again, just press Enter if you are in doubt.  After this is done, the script will ask where you want to fetch the WeBWorK code from (you should choose the defaults), and will get to work.  Some parts of this can take a long time....

Once you are done with the installation, hopefully it finished without errors, you can find the installation log in your root WeBWorK directory.  Usually this is /opt/webwork/webwork_install.log.  This log is a pretty extensive list of everything that the installer script did.  Its useful to keep around so that you can troubleshoot a broken installation, or just modify it so that it suits your needs better.  If the install fails for any reason feel free to post your issue here or ask your question on the forums or the irc channel.  

If the installation succeeded you should be able to access your server by visiting http://localhost:8888/webwork2 on your host machine's browser. 

And now for the surprise (you didn't peek did you...).  By default this version of the installation script installs the new prototype interface WeBWorK3.  You can try it out by visiting the WeBWorK3 link on the left hand side of the page.  You should end up at something which looks like this: 

While its still in the early stages, one of the main features of this new interface is that it is responsive.  No more form based "submit my changes" editor pages.  This interface records your changes as you make them, making it feel much more interactive.  Its not feature complete yet, but a lot of the big things are there.  You can read about the technical side of things here and if you run into problems you can visit the WeBWorK irc channel or email Peter Staab, the main developer.  If you want to back out of the (maybe slightly unstable) ww3 branch you can do so very easily using git.  Just use the command

git checkout release/2.9

in your main webwork2 directory, probably /opt/webwork/webwork2.  Note: release/2.9 will be merged into develop sometime over the summer, as will the ww3 branch of ww_install, so these instructions may get slightly out of date.