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.)
- Web interface for uploading text files of any kind (not just code files)
- The upload function stamps all files uploaded with the user who uploaded it and the date and time as a c++ commented field at the top of the file
- A message board for exchanging ideas, comments, etc.
- An interface for editing a user guide or other documentation online
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 versionsI'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.
- In code/submit.html, edit the html at the top of the page to use your names. Don't use spaces in the "option value=" field.
- In the front page index.shtml, again edit the names and email addresses to match your team. Change the page title too if you like.
- In notes/submit.html again edit the names. You can copy/paste the html from the first step.
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.
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
- Files are stored on the unix machine with control-Ms at each newline character. This is an artifact of the file upload process and is a non-issue for the most part. If you try to copy and compile the code as viewed from a unix terminal it'll probably break, but web browsers ignore the ^Ms and don't display them, making copy/paste simple if done from the web interface.
- Sometimes code uploaded will get interpreted as html. For example, a while loop with no spaces between the < or > signs. Adding spaces around these characters fixes this.This: for (i = 0; i < 100; i++) Not this: for (i=0;i<100;i++)
- The CGIs should really run SUID. This would not require directory permissions to be so liberal. It wouldn't make it totally secure, but it would be better. Possible issue is that some webservers don't allow SUID CGIs to run. (What if the cgi was owned by root!)
- It should just use one copy of cgi-lib.pl. This would be easy to fix.
- Move the list of usernames into a file and then include that file with an SSI. That would mean only one file to change when installing.
- Allow for binary file uploads. I've seen some really nice java-based dialog boxes for file uploads that present the user with the standard windows dialog box, the user just double clicks on a file, and it starts uploading. Right now all non-text files must be uploaded by some means other than this interface. This is probably the biggest thing missing from this system.
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, email@example.com.