CommuteCal.com Track alternative transportation commuters
with Commute Calendar™!

Commute Calendar Installation Documentation

Written by Korey Pelton on June 28, 2011

This documentation is written for customers who have purchased a copy of Commute Calendar and want to install it on their own server. Installation should be quite simple and should take a hour or less for those who are familiar with a Linux or UNIX environment. Questions about installation or operation can be directed to the author of Commute Calendar, Korey Pelton (pelton@peltonweb.com).

System Requirements

So far, Commute Calendar has been verified in the following environment:
  • Linux with kernel 2.6.x
  • Apache Web Server 2.0 and 2.2
  • Perl 5.8.8 and 5.10.1
  • MySQL 5.0 and 5.1
The Commute Calendar code uses only mature features of all the above software, therefore it is highly reliable and should work fine with various versions of the above software.

Your Installation Package

You should have received a zipped installation package from Korey Pelton. Inside is the following:
  • An app directory. This contains the actual Commute Calendar web programs.
  • A cronjobs directory. This contains cron scripts for sending email and keeping your database backed up regularly.
  • A crontab.txt file. This contains the cron jobs you'll enter into cron.
  • A README.txt file that contains a link to the online documentation.
  • A rsync.sh file. This is a small shell script that can be used to sync your local files to your web site.
  • A tables.sql file which contains the SQL used to create all the database tables needed by Commute Calendar.

Setting Up The Database

You may use either the MySQL monitor program on your Linux command line or a tool such as PHPMyAdmin to create the Commute Calendar tables in your MySQL database. Simply login to MySQL using one of those tools and execute the SQL in the tables.sql file.

Configuring The Web Application

Configuration of the web application ranges from quick-and-easy to fairly-time-consuming, depending on the level of configuration you want. Configuration of Commute Calendar could very well be consolidated into just a couple of configuration files, but that would decrease the level of configurability of the application, and you'd miss out on perusing the files and directories of the application. That, and getting configuration down to just a couple of files would require a lot more time on my part. :-)

Getting It Up And Running

The following steps will allow you to edit a few parameters, upload the files, and have Commute Calendar up and running in a few minutes.
  1. Edit app/lib/db.pl to correspond to your database's credentials and location.
  2. Edit app/lib/php/db.php to correspond to your database's credentials and location.
  3. Edit the $administrator_password variable at the top of app/auth/login.cgi. To login to the web application as administrator, go to the login page in your web browser and use the username "admin" and the password you set in this file.
  4. Commute Calendar uses Google reCAPTCHA for security against Web bots. If you do not have a public and private reCAPTCHA key for your web site, you will need to visit http://www.google.com/recaptcha to get them. It's free and easy to use. Enter these keys into the corresponding variable at the top of app/lib/php/recaptchalib.php.
  5. Take a look at the require "lib/db.pl"; and require "lib/passwords.pl"; lines at the top of app/lib/scripts/resetemail.pl and app/lib/scripts/signupemail.pl. The app/reset/send.php program executes resetemail.pl and the app/reset/verify.php program executes signupemail.pl. You may have to edit those lib paths in the Perl programs so that the above PHP programs can find them. Both of the Perl programs queue up email to send to the recipient, so if you don't get any email after a few minutes, try setting the lib path to an absolute path or a slightly different relative path.
  6. Upload the contents of the app directory to your web server, and then go to the directory in your web browser. A login page should appear (index.php). You can then follow the link to sign-up and give Commute Calendar a test drive!

Further Configuration Options

As you can see, the logo and some of the wording is customized for Portneuf Valley Bike To Work Month. You probably want to customize the application for a different entity, so here is a listing of files where these parameters are set. These are brief descriptions only, but reading the actual files will reveal the details; some of the files actually have good comments!
  • The HTML headers and footers that appear on each of the CGIs are set in app/lib/headfoot.pl. In this file, there are separate headers for authenticated CGIs and public CGIs.
  • Here is a listing of the header and footer files that correspond to PHP programs (the names of the header and footer files correspond roughly to the top level directory in which their parent program resides):
    • app/lib/php/login_head.html is used by app/auth_failed.php and app/index.php.
    • app/lib/php/reset_head.html is used by programs in the app/reset/ directory.
    • app/lib/php/share_head.html and app/lib/php/share_foot.html are used by programs in the app/share/ directory.
    • app/lib/php/foot.html is used by app/signup.php, app/auth_failed.php, app/verify.php, and app/index.php.
  • The administration section of Commute Calendar uses files in the app/lib/admin/ directory for the header, footer, and text that appears on the pages.
  • The following files contain text that appears in the "share toolbar" (Facebook, Twitter, and other links) throughout the application.
    • app/lib/instructions.pl
    • app/group/view.cgi
    • app/stats/view.cgi
    • app/signup.php
    • app/index.php
    • app/public/top_companies.cgi
    • app/public/top_participants.cgi

Troubleshooting Tips

Here are some helpful and tips to avoiding problems and or troubleshooting problems if they arise.
  • Set appropriate permissions for your web files. HTML, PHP, and Perl (.pl) files should be chmod 644, CGI files and all directories should be 755, and cron scripts (and the related db.pl file) should be 700.
  • I have found that a lot of problems with CGIs can be resolved by just running the CGI program from the command line (for instance, execute ./app/auth/login.cgi), and this will produce some kind of useful error if something is wrong. As is mentioned above, there are 2 PHP programs that run Perl scripts and this can present a slightly different set of issues related to permissions and file system paths. If you have problems with this, consult your web server error log. You can also write a test PHP that runs at test Perl script, and through experimentation you can figure out what the file system looks like from PHP's perspective.
  • Make sure you run your cron job scripts from the command line to verify that they aren't producing any errors.

For More Information

All the answers to questions can be obtained from reading the Commute Calendar source code. If you still have questions or get stuck, current and potential customers can email Korey Pelton at pelton@peltonweb.com with questions about Commute Calendar. This document will be updated as frequently as possible based upon customer questions, concerns, and suggestions.
Peltonweb.com