A basic web-based code sharing system

What for? | Features | What you need | Getting it | How it works | Troubleshooting | Fix-it list | Miscellaneous


Note/Update: What is done here is a lot easier with PHP! I would recommend doing this kind of work with Apache/PHP over the way it's done in this document. --Rich


What this is for and why I did it

Often times as students we find ourselves working on group projects. CS160 is such a class, and when I took the class in the Fall of '01, I saw that exchanging code was going to be an ongoing activity and, at the same time, an ongoing problem. I didn't want to deal with floppy disks, burning CDs every class, etc. (with bitmaps, the code didn't always fit on a single floppy). But as a group, we are all working on some part of the code whenever each of us had the time to work on it. Meeting outside of class is difficult at best. I wanted there to be an easy way for us to communicate and share code with each other. Email can be a solution here, but this is sometimes awkward depending on how users' email programs deal with attachments. This also requires a user (generally speaking) to be at their "own" computer to check email.

A web-based interface to handle code sharing and communicate seemed a good solution, and that is what this page documents. Here is a non-editable example of what it looks like and how we used it during that semester.

At the same time, I added a basic message board functionality and a place for all of us to have access to our project documentation -- and be able to edit it online. No worrying about which version is the latest, whether everything got included, etc., since everybody works from the same live document.

(Keep in mind this information is here as a starting point. This is what I used during this course, but there is nothing at all preventing you from modifying this or just using the ideas to make your own system. Better ways than this exist to accomplish the same tasks.)


Features


What you'll need to use this as is

You'll need a Unix account on a machine running a web server that has server side includes enabled. This is generally the default case but not always. If you are using apache then this code will probably work as is without any modifications (other than editing names and stuff). You'll also need perl on this machine - I've never seen a unix machine without perl installed so there shouldn't be a problem there. Unfortunately, the department mcs machines aren't running a web server on them (at least as of fall '01 they weren't), so you'll have to find such a machine on your own. Shell accounts running web servers can be had at many local ISPs for $20 or less per month. This may run on NT web servers as well, but I didn't try it.

In general, this works best with one person managing the site and handling the posting of binary files onto the site. (Remember there is no way to upload binary files). Generally this person should check their email often for email from other team members with attachments that need to be posted, and then post them to the site in the files section.


Getting the code and installing it

The code is here as a tar file (about 130 KB). An individual listing of the files is here.

There's nothing real fancy or complicated about this setup. It's just a few perl scripts, html files, and directories. When you untar the file (use the command: tar -xvpf 160files.tar in the directory where you want this to be - remember it has to be a web directory) you should see the following directory structure: 

   160/
      code/
	 cgi-lib.pl		# standard perl cgi library
	 index.html		# code index page
	 submit.cgi		# perl, writes files to this directory
	 submit.html		# the html form for submitting code
      index.shtml		         # the main project page
      notes/			
	 cgi-lib.pl		
	 index.html		# bulletin board page
	 submit.cgi		# perl, post a new message
	 submit.html		# the html form for posting a new message
      userguide/
	 cgi-lib.pl		
	 guide-old.html		# a backup of the old version, rotated each update
	 guide.html		# the current version
	 guide2.html		# the version being edited
	 index.html@ -> guide.html   # just a link so the guide auto-loads
	 modify.shtml		# the html form for modifying the user guide
	 update.cgi*		# perl, updates user guide and rotates versions
I'm going to assume that this code will work as is for you, and will just mention here what you'll want to customize for yourself and where to find it. Suggestions and troubleshooting for code that doesn't work are in the troubleshooing section at the bottom. These are just the required changes, feel free to change other things if desired.

And that's it.


How it works/concept

Server side includes (SSIs) are a web server feature that allows psuedo-dynamic web content, produced at page request time by the web server. A good example would be a web page that always gives you the current time when you load it but doesn't update it after that unless you refresh the page. SSIs are short commands embedded in the HTML, that have HTML comment characters before and after them. Here's the code for a file timestamp SSI: 

<!--#flastmod file="userguide/guide.html"-->

SSIs are used in here to get file modification dates and times, useful for determining how old a piece of code might be. A file include SSI is also used in the user guide portion of the site, loading up the user guide into the form so the user can edit it.

Without SSIs this code doesn't become totally useless, but it does make the site a bit less informative. If you don't have SSIs enabled on the web server you're using, just delete the SSIs from the code. Realize that the user guide portion of the site requires a file include SSI to work, so you'll lose this functionality without SSIs. (But you could certainly code up a short perl script to keep this functionality without using SSIs).

The rest of the site is straightforward perl with liberal file and directory permissions. Web servers don't run as root, (They shouldn't!!!) so to give the web server access to write files in your directories, you'll need to give the right directories group or other write permission. If you untarred the file with the -p option, then you shouldn't need to play with permissions.

A better solution is presented below in the fix it list, but I didn't bother implementing it.

A note about security is in order. Since we have other-writable directories with this setup, realize that there is nothing stopping anyone from uploading a script and trying to run it from the web in attempt to compromise the machine. I tend to beleive in "security by obscurity", that is, set up the site and don't link to it from anywhere and don't give the URL out to people you don't know. Even better would be to password protect the site. This is easily accomplished on all web servers, SSIs enabled or not, using .htaccess files or their equivelant.


Troubleshooting

If something's not working, check file permissions. Files that get updated should be 666, files that do not get updated should be 644, and directories that are a location for new files to be uploaded into need to be 777. If you untarred the file with the -p option, permissions should be OK as is. Check SSIs by either asking the server administrator or playing with them. Make sure that the file extension for files that use SSIs is .shtml on the unix machine in question as well.


Known issues/fix it list


Miscellaneous

Feel free to take this and do whatever with it. If you want to modify it, add features, etc, go for it! You don't have to send me email, but if you find it particularly useful, crummy, whatever, it would be fun to hear from you. Enjoy. Good luck on your projects! -Rich, sjsu160@richp.com.