WSO web development

WSO's web site is a work in progress. If you know web design or Perl, or if you want to see how it's done, you're welcome to check out a copy of the code and go to work. This page will tell you how to get started.

SSH to WSO

If you don't have a WSO account, email Evan, Mike, or Ben. One of them will hook you up. A WSO account is not your 06abc account. It is the first letter of your first name followed by seven letters of your last name. Once you have an account, go ahead and log in:

Windows: get yourself a copy of Putty. wso.williams.edu is the host.

Mac/Linux: Open up a Terminal or a console, and type

ssh wso.williams.edu

Set up a web server

This part sounds scary, but most of the configuration has been done for you already. First we copy the server files into your home directory:

cp -R /var/web .

Now we just change the configuration files to work for your personal account. Change directory into your new "web" directory:

cd web

Next, type these instructions EXACTLY. Note the back-ticks in the second command. ( ` ). The back-tick is on the key right above tab on the keyboard.

sed -i .bak "s/USER/$USER/g" apache/*.conf apache/apache_test apachectl
sed -i .bak "s/UID/`expr 50000 + $UID`/g" apache/*.conf
rm apache/*.bak

So the mysterious second command will tell the web server what port to listen on. Programs listen on different ports so that when you make a network request of WSO (SSH, the web, e-mail), it knows which program should handle the request. Your server will listen on the port number 50000 plus your user id. (That makes sure everyone has a unique port.) To find out what that is, type

expr 50000 + $UID

Write that number down for later.

Get the code

Let's get a fresh copy of the code. On WSO, type

svn co file:///var/svn/wsonet ~/web/wsonet
svn co file:///var/svn/wsorails ~/web/wsorails

If you just want to see what the code is like, you can poke around those two folders. "wsonet" contains the part of the site written in Perl. "wsorails" contains the part of the site written in Ruby. Most of the site is currently in Perl, but new services will be in the wsorails folder.

For those of you afraid of the command line, you can now look at the files by logging into WSO over SFTP. Check out the bit on SFTP at How to transfer files to WSO.

Of course, to actually work on the code, you'll want to know what effects your changes have. That's why we want to

Start the server

OK, we're ready to start the web server. Type this:

~/web/apachectl start

If everything went well, it'll say "httpd started", or something to that effect. Hooray!

Before breaking out the champagne, we need to check to see that the server actually works. Unfortunately, you can't just pop open a web browser and surf to your new site. WSO's servers are behind a firewall. The firewall only allows connections on certain ports. Yours is not one of them.

Setting up port forwarding

The way through the firewall is to pretend that the web server is running on your computer and not on WSO. We'll use a technology called port forwarding to send web requests to your machine through an SSH connection to your server on WSO. This is, simply, awesome.

And not too hard.

Mac/Linux

Open up a Terminal, and type

ssh -N -p 22 -f -2 -L 8000/127.0.0.1/53717 emiller@wso.williams.edu

EXCEPT instead of 53717, put the port number that you wrote down, and instead of "emiller", type your WSO account name. Unfortunately, you'll have to run this command somewhat frequently, since SSH connections close when your computer reboots or goes to sleep (or WSO crashes, or whatever...). To make this a little less tedious, open the file called .bashrc in your home directory and add this line:

alias wso8000='ssh -N -p 22 -f -2 -L 8000/127.0.0.1/53717 emiller@wso.williams.edu'

Again, make the substitutions for your own port and username. Now, if you need to establish the connection, just type "wso8000" in a terminal window. You can pick a different alias, of course.

Windows

Putty lets you do port forwarding, too. You can read more about it here:

http://the.earth.li/~sgtatham/putty/0.57/htmldoc/Chapter3.html#S3.5

Here are the settings you'll need:

Source port: 8000
Destination port: (your special port)
Destination host: localhost

Try out the server

On-campus: Open up a web browser and point it to "http://localhost.williams.edu:8000/". The WSO site should show up. Congratulations!

Off-campus: On a Mac or Linux box, add this line to the file /etc/hosts:

127.0.0.1    localhost.williams.edu

That makes your machine think its address is localhost.williams.edu, which is necessary for cookies to work the way your server is configured. Now point your web browser to http://localhost.williams.edu:8000/, and check it out.

Of course, if it doesn't work, please describe your problem on Talk:How to hack on the WSO site.

Now, you can change a file in ~/web/wsonet/site, and the change will show up on your development server at this address. Sweet.

Making changes

Nice work getting this far. So now you actually want to do something with the code. Check out How to write a web service on WSO; it'll give you a nice overview of how things work, and also point you to references where you can learn Perl and HTML.

Kai is the webmaster. Contact him if you'd like to change the WSO site, add a new service, or fix a bug. If he gives you the go-ahead, you're in good shape, so go to work. Once you think your change is ready for the world, you'll need to get permission to commit changes to our code repository, where it will be tested and deployed. Email Evan about that. He'll take care of you.