Difference between revisions of "WSO web development"

m
 
(19 intermediate revisions by 3 users not shown)
Line 1: Line 1:
[http://wso.williams.edu 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.
+
{{outdated}}
 +
[[Category:How-To]] [[Category:Computers]] [[Category:WSO]]
 +
[http://wso.williams.edu WSO's web site] is a work in progress. You can always see "the next step" at http://wso.williams.edu:3000, where the latest "stable" (stable being a relative term) version of the next update to the site lives. If you're impatient about the new facebook, or you know web design or Ruby, or if you just 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.
  
  
 +
== Get a Subversion account ==
  
==SSH to WSO==
+
Email root at wso.williams.edu to get an account and password so that you can checkout a copy of the code from our Subversion repository. You'll need this when running any of the svn commands below.
  
If you don't have a WSO account, email [http://wso.williams.edu/facebook/view?unix=06emm Evan], [http://wso.williams.edu/facebook/view?unix=07mg_2 Mike], or [http://wso.williams.edu/facebook/view?unix=06bdc 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:
+
== Choose your environment ==
 +
 
 +
Working on the WSO site will require running your own development copy of the site. There are two basic ways to go about this.
 +
 
 +
1. Run your development server in your account on WSO's user server. This requires the following:
 +
* A WSO shell account.
 +
* A WSO subversion account.
 +
* A computer with an ssh client (ssh on *nix or Mac OS X, PuTTY on Windows).
 +
* Some familiarity with the command line.
 +
2. Run your development server on your machine. This requires the following:
 +
* A WSO subversion account.
 +
* A computer.
 +
* Familiarity with installing command line software (preferably via a package manager).
 +
 
 +
Though setting up a dev server on your own machine may require more investment of time up front, it is ultimately more flexible, since you have more control over and easier access to your environment.
 +
 
 +
==Option 1: Set up a development server in your WSO account==
 +
 
 +
===SSH to WSO===
 +
 
 +
If you don't have a WSO account, email root at wso.williams.edu. One of them will hook you up. A WSO account is not your 06abc or abc1 account. It is the first letter of your first name followed by up to seven letters of your last name. Once you have an account, go ahead and log in:
  
 
'''Windows''': get yourself a copy of [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html Putty]. wso.williams.edu is the host.
 
'''Windows''': get yourself a copy of [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html Putty]. wso.williams.edu is the host.
Line 11: Line 34:
 
'''Mac/Linux''': Open up a Terminal or a console, and type
 
'''Mac/Linux''': Open up a Terminal or a console, and type
  
  ssh wso.williams.edu
+
  ssh username@wso.williams.edu
  
==Set up a web server==
+
where username is your WSO username (remember, not your 06abc OIT id).
  
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:
+
===Check out the code===
  
cp -R /var/web .
+
Once you've logged in with SSH, you're ready to check out your very own copy of the WSO code. In your home directory, or wherever you'd like to keep your copy of the WSO site, run the following command to use Subversion to check out the code. (Don't forget the dot at the end!) This will spew a whole log of output onto your screen, listing all the files it's checking out. You can replace "wso-devel" with whatever name you want for your local copy of the code.
  
Now we just change the configuration files to work for your personal account. Change directory into your new "web" directory:
+
svn checkout svn://wso.williams.edu/wso-on-rails/trunk wso-devel
  
cd web
+
Now change directory into the code directory:
  
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.
+
  cd wso-devel
  
sed -i .bak "s/USER/$USER/g" apache/*.conf apache/apache_test apachectl
+
We need to create a log file for your site so it doesn't complain directly to you.
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
+
touch log/development.log
  
expr 50000 + $UID
+
Now your site is ready to run! If you just want to poke around you can do that without starting the server (check out [[How to transfer files to WSO]]), but if you want to make changes and see what happens, keep reading.
  
''Write that number down for later.''
+
===Start the server===
  
==Get the code==
+
But first you need your own personal port to run it on. Find this by running the following command. You'll want to save the output of this for future reference.
  
Let's get a fresh copy of the code. On WSO, type
+
  expr 50000 + $UID
 
 
  svn co file:///var/svn/wsonet ~/web/wsonet
 
 
 
If you just want to see what the code is like, you can poke around the wsonet 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
+
To start the server run the following command in the wso-devel directory, replacing your_port with the number we generated above.
  
==Start the server==
+
/opt/local/bin/ruby script/server -p your_port
  
OK, we're ready to start the web server. Type this:
+
If you see something like the following, then you're in business.
  
  ~/web/apachectl start
+
  => Booting Mongrel (use 'script/server webrick' to force WEBrick)
 +
=> Rails application starting on http://0.0.0.0:your_port
 +
=> Call with -d to detach
 +
=> Ctrl-C to shutdown server
 +
** Starting Mongrel listening at 0.0.0.0:your_port
 +
** Starting Rails with development environment...
 +
** Rails loaded.
 +
** Loading any Rails specific GemPlugins
 +
** Signals ready.  TERM => stop.  USR2 => restart.  INT => stop (no restart).
 +
** Rails signals registered.  HUP => reload (without restart).  It might not work well.
 +
** Mongrel available at 0.0.0.0:your_port
 +
** Use CTRL-C to stop.
  
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.
 
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==
+
===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.
+
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===
+
====Mac/Linux====
  
Open up a Terminal, and type
+
Open up a Terminal on your own machine, and type
  
  ssh -N -f -2 -L 8000/127.0.0.1/53717 emiller@wso.williams.edu
+
  ssh -N -p 22 -f -2 -L 3000/ursula/your_port username@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:
+
EXCEPT instead of your_port, put the port number that you wrote down, and instead of "username", 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 on your own machine and add this line:
  
  alias wso8000='ssh -N -f -2 -L 8000/127.0.0.1/53717 emiller@wso.williams.edu'
+
  alias wso3000='ssh -N -p 22 -f -2 -L 3000/ursula/your_port username@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.
+
Again, make the substitutions for your_port and username. Close the Terminal window and open a new one. Now, if you need to establish the connection, just type "wso3000" in a terminal window. You can pick a different alias, of course.
  
===Windows===
+
====Windows====
  
 
Putty lets you do port forwarding, too. You can read more about it here:
 
Putty lets you do port forwarding, too. You can read more about it here:
Line 81: Line 106:
 
Here are the settings you'll need:
 
Here are the settings you'll need:
  
  Source port: 8000
+
  Source port: 3000
 
  Destination port: (your special port)
 
  Destination port: (your special port)
  Destination host: localhost
+
  Destination host: ursula
 +
 
 +
Continue to the Common Instructions.
 +
 
 +
== Option 2: Run on your own machine==
 +
 
 +
Disclaimer: The author has done this on various flavors of *nix and on Mac OS X, but knows nothing about Windows. It is possible on Windows, but no guarantees that it will just work. Google is your friend.
 +
 
 +
===Install software===
 +
 
 +
====With your package manager====
 +
 
 +
Using your favorite package manager, install the following:
 +
 
 +
* subversion
 +
* sqlite3
 +
* ruby (1.8.6)
 +
* ruby ldap (rb-ldap 0.9.1)
 +
* ImageMagick
 +
* ruby gems, a package manager for ruby packages
 +
 
 +
=====Notes=====
 +
Make sure that these appear in your $PATH.
 +
 
 +
On Mac OS X Leopard, the built-in ruby comes with ruby gems installed, so you may be able to skip those two. On Tiger and earlier, use MacPorts to install all of the above (mongrel is still optional).
 +
 
 +
====With ruby gems====
 +
 
 +
Using gem install the following:
 +
 
 +
* rails
 +
* RedCloth
 +
* simple-rss
 +
* sqlite3-ruby
 +
* rmagick
 +
* optional: mongrel
 +
 
 +
You can install all of this with the command
 +
 
 +
  gem install rails RedCloth simple-rss sqlite3-ruby mongrel -y
 +
 
 +
On any *nix system or Mac OS X, you'll probably need to run this with sudo. No idea about Windows.
 +
 
 +
If you have any trouble with this, post to [[Talk:WSO web development]] or email bwood at wso.
 +
 
 +
===Check out the code===
 +
 
 +
In your home directory, or wherever you'd like to keep your copy of the WSO site, run the following command to use Subversion to check out the code. This will spew a whole log of output onto your screen, listing all the files it's checking out. You can replace "wso-devel" with whatever name you want for your local copy of the code.
 +
 
 +
svn checkout svn://wso.williams.edu/wso-on-rails/trunk wso-devel
 +
 
 +
Now change directory into the code directory:
 +
 
 +
cd wso-devel
 +
 
 +
We need to create a log file for your site so it doesn't complain directly to you.
 +
 
 +
touch log/development.log
 +
 
 +
Now your site is ready to run!
 +
 
 +
 
 +
===Start the server===
 +
 
 +
To start the server run the following command in the wso-devel directory.
 +
 
 +
script/server
 +
 
 +
If you see something like the following, then you're in business. (This is what you'll see if you installed mongrel, otherwise, you'll see similar output from WEBrick, the default server.)
 +
 
 +
=> Booting Mongrel (use 'script/server webrick' to force WEBrick)
 +
=> Rails application starting on http://0.0.0.0:3000
 +
=> Call with -d to detach
 +
=> Ctrl-C to shutdown server
 +
** Starting Mongrel listening at 0.0.0.0:3000
 +
** Starting Rails with development environment...
 +
** Rails loaded.
 +
** Loading any Rails specific GemPlugins
 +
** Signals ready.  TERM => stop.  USR2 => restart.  INT => stop (no restart).
 +
** Rails signals registered.  HUP => reload (without restart).  It might not work well.
 +
** Mongrel available at 0.0.0.0:3000
 +
** Use CTRL-C to stop.
 +
 
 +
 
 +
==Common Instructions==
 +
 
 +
===Build your database===
 +
 
 +
The development version of the WSO site uses SQLite, a file-based database to make it easy to deploy anywhere. To create your database and setup the structure we'll need, just run
 +
 
 +
  rake db:schema:load
 +
 
 +
in the root directory of your copy of the code (e.g. wso-devel).
 +
 
 +
===Add yourself as a user===
 +
 
 +
Also in the root directory of your site, run
 +
 
 +
  rake data:dev:addusers
 +
 
 +
===Optional: update caches===
 +
 
 +
On the production server, these scripts are run every so often to keep the info on the front page up to date. You get some pregenerated caches with the code, but if you want something more realistic, run these.
  
==Try out the server==
+
  ruby script/cron/rss.rb
 +
  ruby script/cron/weather.rb
  
'''On-campus''': Open up a web browser and point it to "http://localhost.williams.edu:8000/". The WSO site should show up. Congratulations!
+
===Try out the server===
  
'''Off-campus''': On a Mac or Linux box, add this line to the file /etc/hosts:
+
Open up a browser and go to http://localhost:3000/
  
127.0.0.1    localhost.williams.edu
+
Of course, if it doesn't work, please describe your problem on [[Talk:WSO web development]].
  
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.
+
Now, you can change a file in wso-devel, and the change will show up on your development server at this address the next time you reload the page in your browser. Sweet. (Some changes esp. to controllers or libraries will require restarting the server, but it's simple.)
  
 +
===Making changes===
  
Of course, if it doesn't work, please describe your problem on [[Talk:How to hack on the WSO site]].
+
Nice work getting this far. So now you actually want to ''do'' something with the code. For now, come to a WSO meeting Tuesdays at 9:30pm in the vicinity of TCL 202, or email wso at wso.williams.edu with questions/interest. With the new Facebook finished, our next big prospect is rewriting old PageKit services (Factrak!) in Ruby on Rails.
  
Now, you can change a file in ~/web/wsonet/site, and the change will show up on your development server at this address. Sweet.
+
It's a good idea to run an update every so often so that your local working copy picks up changes that other people have made. Change directory into your wso-devel directory and run
  
==Making changes==
+
svn update
  
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.
 
  
[http://wso.williams.edu/facebook/view?unix=06cks 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 [http://wso.williams.edu/facebook/view?unix=06emm Evan] about that. He'll take care of you.
+
Email root at wso.williams.edu if you'd like to change the WSO site, add a new service, or fix a bug. If you get 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 add your changes to our code repository, where it will be tested and deployed. Email root at wso.williams.edu about that. They'll take care of you.

Latest revision as of 23:26, May 17, 2019

WSO's web site is a work in progress. You can always see "the next step" at http://wso.williams.edu:3000, where the latest "stable" (stable being a relative term) version of the next update to the site lives. If you're impatient about the new facebook, or you know web design or Ruby, or if you just 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.


Get a Subversion account

Email root at wso.williams.edu to get an account and password so that you can checkout a copy of the code from our Subversion repository. You'll need this when running any of the svn commands below.

Choose your environment

Working on the WSO site will require running your own development copy of the site. There are two basic ways to go about this.

1. Run your development server in your account on WSO's user server. This requires the following:

  • A WSO shell account.
  • A WSO subversion account.
  • A computer with an ssh client (ssh on *nix or Mac OS X, PuTTY on Windows).
  • Some familiarity with the command line.

2. Run your development server on your machine. This requires the following:

  • A WSO subversion account.
  • A computer.
  • Familiarity with installing command line software (preferably via a package manager).

Though setting up a dev server on your own machine may require more investment of time up front, it is ultimately more flexible, since you have more control over and easier access to your environment.

Option 1: Set up a development server in your WSO account

SSH to WSO

If you don't have a WSO account, email root at wso.williams.edu. One of them will hook you up. A WSO account is not your 06abc or abc1 account. It is the first letter of your first name followed by up to 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 username@wso.williams.edu

where username is your WSO username (remember, not your 06abc OIT id).

Check out the code

Once you've logged in with SSH, you're ready to check out your very own copy of the WSO code. In your home directory, or wherever you'd like to keep your copy of the WSO site, run the following command to use Subversion to check out the code. (Don't forget the dot at the end!) This will spew a whole log of output onto your screen, listing all the files it's checking out. You can replace "wso-devel" with whatever name you want for your local copy of the code.

svn checkout svn://wso.williams.edu/wso-on-rails/trunk wso-devel

Now change directory into the code directory:

cd wso-devel

We need to create a log file for your site so it doesn't complain directly to you.

touch log/development.log

Now your site is ready to run! If you just want to poke around you can do that without starting the server (check out How to transfer files to WSO), but if you want to make changes and see what happens, keep reading.

Start the server

But first you need your own personal port to run it on. Find this by running the following command. You'll want to save the output of this for future reference.

expr 50000 + $UID

To start the server run the following command in the wso-devel directory, replacing your_port with the number we generated above.

/opt/local/bin/ruby script/server -p your_port

If you see something like the following, then you're in business.

=> Booting Mongrel (use 'script/server webrick' to force WEBrick)
=> Rails application starting on http://0.0.0.0:your_port
=> Call with -d to detach
=> Ctrl-C to shutdown server
** Starting Mongrel listening at 0.0.0.0:your_port
** Starting Rails with development environment...
** Rails loaded.
** Loading any Rails specific GemPlugins
** Signals ready.  TERM => stop.  USR2 => restart.  INT => stop (no restart).
** Rails signals registered.  HUP => reload (without restart).  It might not work well.
** Mongrel available at 0.0.0.0:your_port
** Use CTRL-C to stop.


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 on your own machine, and type

ssh -N -p 22 -f -2 -L 3000/ursula/your_port username@wso.williams.edu

EXCEPT instead of your_port, put the port number that you wrote down, and instead of "username", 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 on your own machine and add this line:

alias wso3000='ssh -N -p 22 -f -2 -L 3000/ursula/your_port username@wso.williams.edu'

Again, make the substitutions for your_port and username. Close the Terminal window and open a new one. Now, if you need to establish the connection, just type "wso3000" 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: 3000
Destination port: (your special port)
Destination host: ursula

Continue to the Common Instructions.

Option 2: Run on your own machine

Disclaimer: The author has done this on various flavors of *nix and on Mac OS X, but knows nothing about Windows. It is possible on Windows, but no guarantees that it will just work. Google is your friend.

Install software

With your package manager

Using your favorite package manager, install the following:

  • subversion
  • sqlite3
  • ruby (1.8.6)
  • ruby ldap (rb-ldap 0.9.1)
  • ImageMagick
  • ruby gems, a package manager for ruby packages
Notes

Make sure that these appear in your $PATH.

On Mac OS X Leopard, the built-in ruby comes with ruby gems installed, so you may be able to skip those two. On Tiger and earlier, use MacPorts to install all of the above (mongrel is still optional).

With ruby gems

Using gem install the following:

  • rails
  • RedCloth
  • simple-rss
  • sqlite3-ruby
  • rmagick
  • optional: mongrel

You can install all of this with the command

 gem install rails RedCloth simple-rss sqlite3-ruby mongrel -y

On any *nix system or Mac OS X, you'll probably need to run this with sudo. No idea about Windows.

If you have any trouble with this, post to Talk:WSO web development or email bwood at wso.

Check out the code

In your home directory, or wherever you'd like to keep your copy of the WSO site, run the following command to use Subversion to check out the code. This will spew a whole log of output onto your screen, listing all the files it's checking out. You can replace "wso-devel" with whatever name you want for your local copy of the code.

svn checkout svn://wso.williams.edu/wso-on-rails/trunk wso-devel

Now change directory into the code directory:

cd wso-devel

We need to create a log file for your site so it doesn't complain directly to you.

touch log/development.log

Now your site is ready to run!


Start the server

To start the server run the following command in the wso-devel directory.

script/server

If you see something like the following, then you're in business. (This is what you'll see if you installed mongrel, otherwise, you'll see similar output from WEBrick, the default server.)

=> Booting Mongrel (use 'script/server webrick' to force WEBrick)
=> Rails application starting on http://0.0.0.0:3000
=> Call with -d to detach
=> Ctrl-C to shutdown server
** Starting Mongrel listening at 0.0.0.0:3000
** Starting Rails with development environment...
** Rails loaded.
** Loading any Rails specific GemPlugins
** Signals ready.  TERM => stop.  USR2 => restart.  INT => stop (no restart).
** Rails signals registered.  HUP => reload (without restart).  It might not work well.
** Mongrel available at 0.0.0.0:3000
** Use CTRL-C to stop.


Common Instructions

Build your database

The development version of the WSO site uses SQLite, a file-based database to make it easy to deploy anywhere. To create your database and setup the structure we'll need, just run

 rake db:schema:load

in the root directory of your copy of the code (e.g. wso-devel).

Add yourself as a user

Also in the root directory of your site, run

 rake data:dev:addusers

Optional: update caches

On the production server, these scripts are run every so often to keep the info on the front page up to date. You get some pregenerated caches with the code, but if you want something more realistic, run these.

 ruby script/cron/rss.rb
 ruby script/cron/weather.rb

Try out the server

Open up a browser and go to http://localhost:3000/

Of course, if it doesn't work, please describe your problem on Talk:WSO web development.

Now, you can change a file in wso-devel, and the change will show up on your development server at this address the next time you reload the page in your browser. Sweet. (Some changes esp. to controllers or libraries will require restarting the server, but it's simple.)

Making changes

Nice work getting this far. So now you actually want to do something with the code. For now, come to a WSO meeting Tuesdays at 9:30pm in the vicinity of TCL 202, or email wso at wso.williams.edu with questions/interest. With the new Facebook finished, our next big prospect is rewriting old PageKit services (Factrak!) in Ruby on Rails.

It's a good idea to run an update every so often so that your local working copy picks up changes that other people have made. Change directory into your wso-devel directory and run

svn update


Email root at wso.williams.edu if you'd like to change the WSO site, add a new service, or fix a bug. If you get 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 add your changes to our code repository, where it will be tested and deployed. Email root at wso.williams.edu about that. They'll take care of you.