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.
Contents
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 -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 -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.