Installing OHMS on Stanford’s WWW Servers
Dennis Sun and Naftali Harris
September 23, 2015
1
Requesting a Course Website
The first step is to request a course website from Stanford IT Services. This will give you a course
website with URL of the form http://www.stanford.edu/class/stats60. (NB. In everything
that follows, you should replace stats60 with the appropriate code for your course). As of this
writing, you can request a course website at
https://tools.stanford.edu/cgi-bin/course-request
The options should be mostly self-explanatory, and they are explained in detail at the bottom of
that webpage. There are two features that you’ll need:
• restricted directory: this creates a directory that only students enrolled in the class can
access. This directory comes with a .htaccess file that can be used to control access to
OHMS, as well.
• cgi-bin directory: this allows you to write executable Python, Perl, and PHP scripts that
can be called. Since OHMS is written in Python, this is essential.
Make sure you check the “yes” box next to these two options. I recommend that you also check
the box next to redirect; this gives you a nicer URL of the form stats60.stanford.edu. I also
recommend that you do not check the Clone (copy content from current course dir) option.
You do not want to carry over files from the existing version of the course website, as it will most
likely just cause confusion.
Your request will be processed within 1 business day. Once you receive the e-mail confirmation, you can access your course directory by logging onto Stanford’s AFS servers (i.e.,
corn.stanford.edu). The directory for the course is located at
/afs/ir/class/stats60
Since you don’t want to have to type that every time you access your course directory, I recommend
adding a symlink to this directory in your home directory ~/. You can do this by typing
ln -s /afs/ir/class/stats60 ~/
at the command line. Now you can access the directory by simply typing
cd ~/stats60
Inside this folder, you should see the folder WWW/, which contains the files publicly displayed at
http://www.stanford.edu/class/stats60/,
as well as the folder cgi-bin/, which contains the CGI files which will are publicly available at
http://www.stanford.edu/class/stats60/cgi-bin/.
1
2
Requesting a MySQL Database
OHMS stores the questions and student responses in a MySQL database. Stanford IT Services
provides MySQL hosting free of charge. As of this writing, you can request a MySQL database at
https://itservices.stanford.edu/service/sql.
Click “Request MySQL Service,” agree to the terms of service, and you will be brought to a
form that already contains your SunetID, Full Name, and Email. It also asks for the following
information:
• Organization Type: For you, this should be “Class”.
• Organization Name: For you, this should be stats60 (or the code for your course).
• Database Name: This can be whatever you want. We use the convention prod for “production.” (Note that the database name you will actually get is something like c_stats60_prod.)
• Description: Enter some description here. As far as I can tell, this doesn’t really matter.
The MySQL database will be set up automatically, and you will receive an e-mail with the
database name and login username (something like cstats60prod). Note that they do not send
the login password to you. If you log into AFS again, you should see a new directory in the stats60
directory, namely db_private. This directory contains a file db_info that contains the database
name and login username, along with the login password.
If you only have one database, you do not have to worry about this. The code is set up to
automatically read the database information from the file db_info. However, if you have multiple
databases, you may need to hard code the URL of the MySQL database into the options file,
explained below.
3
Downloading OHMS
The entire OHMS codebase is available on github at http://github.com/dlsun/ohms. We recommend that you clone this repository somewhere in your course directory on AFS. In what follows,
we assume that you clone the repository into the directory ~/stats60/code/.1 To do this, first we
have to make the directory code if it does not already exist:
mkdir ~/stats60/code
Next, we go to the directory and clone the OHMS git repository inside the directory:
cd ~/stats60/code
git clone https://github.com/dlsun/ohms.git
The directory ohms/ should now appear inside ~/stats60/code/.
1
The reason that we clone into ~/stats60/code/ rather than directly into ~/stats60/ is because the Python
package and the git repository are both named ohms. We wouldn’t want to accidentally overwrite one with the other.
2
4
Configuring and Installing
We are now ready to install OHMS. It is important to understand that OHMS is a CGI application
written in Python. It assumes that you are using Python 2.7, and additionally requires the following
Python packages:
1. SQLAlchemy
2. Flask
As of this writing, these are all installed on the CGI servers. However, you should be aware of
these dependencies in case Stanford IT upgrades their servers and forgets to re-install them. (You
can file a HelpSU request to ask them to install any of these packages on the CGI servers.) Check
to make sure that you have all dependencies before proceeding.
Go to ~/stats60/code/ohms/. You should see the options/ directory, which contains two
files:
• local_options.py: This is the options file if you plan to run OHMS on your local machine
(e.g., for testing). You do not need to worry about this otherwise.
• options.py: This is the main options file. You only need to pay attention to the items
marked * below. If you used all the default settings, you should not have to change any items
marked –.
* title: the title of your course
* instructor: the name of the instructor
* base_url: the URL for your course website. You should change stats60 to the appropriate code for your course.
– cgi: the location of the CGI script, relative to base_url.
– static: the location of the static (e.g., images, CSS, Javascript) files, relative to
base_url.
* base_dir: the location of your course directory on the AFS servers. Again, this should
only require changing stats60 to your course code.
– upload_dir: any files that students upload through the homework system will be stored
in this directory on AFS.
– htaccess: the location of the .htaccess file that you wish to use to control access to
OHMS. By default, anyone with a Stanford login can access it; however, by uncommenting the second line, you can limit access to only students enrolled in the course.
– get_db(): this function retrieves the MySQL username, password, and database name
from the db_info file that is automatically generated when you request a MySQL
database (which is assumed to live in the db_private folder...keep this in mind in case
Stanford IT decides to change the location). However, if you have multiple databases—
or are not using the Stanford-provided MySQL databases—you should hard-code the
return URL (instead of having the system try to read it from db_info).
* admins: a list containing the SUNet IDs of all course administrators. This should include
all instructors, TAs, and graders. These users will be allowed to view student responses
and grades.
3
Once you have made the necessary configurations, go back to the main ohms/ directory and run
the setup script by typing
python setup.py
Note that this script assumes that the ohms repository is in the code/ directory of your course
directory. If it is anywhere else, you will have to edit the root variable inside setup.py. This
script will copy all of the files from ohms/ into the appropriate directories and set all permissions.
5
Updating OHMS
You are now done installing OHMS. If you point your browser to
http://www.stanford.edu/class/stats60/cgi-bin/index.cgi/.2
you should see OHMS. One final note: there will occasionally be updates to OHMS on the git repository. To update your version of OHMS to this latest version, simply go to the ~/stats60/code/ohms/
directory and run
git pull origin master
python setup.py
This should update everything to the latest version of OHMS.
6
Debugging Tips
By default, the Stanford CGI servers do not dump server errors to the user (this would pose a
security risk). You will probably just get a generic “Server error” message. This makes debugging
very difficult. Fortunately, by adding a file to the directory containing the CGI script, you can force
the server to print errors to the user. This file must be called .suexecd (note the leading dot).
The simplest way to add this file is to simply go to the cgi-bin and type
touch .suexecd
This creates the file. To delete it once you’re done, type
rm .suexecd
2
Note the trailing slash! If Stanford IT configured the rewrite rules properly, it should work without the slash,
but keep the slash just in case.
4