Commute Calendar Installation Documentation (PHP Version)

This documentation is written for customers who have purchased a copy of Commute Calendar (PHP version) 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

• Linux with kernel 2.6.x
• Apache Web Server 2.0 and 2.2
• PHP 5
• MySQL 5.0 and 5.1

Your Installation Package

• An app directory. This contains the actual Commute Calendar web programs. Note: all paths shown in this documentation are located in this directory unless otherwise specified.
• A cronjobs directory. This contains cron scripts for sending email and keeping your database backed up regularly.
  • database_backup.sh - an optional database back up script to back up Commute Calendar's data with. Some kind of data back up scheme for Commute Calendar is highly recommended.
  • db.pl - The database function file used by the mailer programs. Edit your database settings in this file.
  • mailer.pl - This is the cron program that sends out emails generated by Commute Calendar (new sign ups, password resets, etc.).
  • massmailer.pl - This cron program that sends out mass emails that the administrator composes (see administration section of Commute Calendar).
• 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 optionally be used to sync your local files to your web site, which is quite handy if you make a lot of changes to Commute Calendar over time. Your PC and the web host must have rsync installed to use this program.
• A tables.sql file which contains the SQL used to create all the database tables needed by Commute Calendar.

Setting Up The Database

1. Open the tables.sql file in a text editor and edit the admin password (see comments near the top of the file). To login to Commute Calendar as administrator, you'll use "admin" as the email address and the password you set here as the password.
2. Edit the emails shown (see the SQL comments surrounded by /* and */ characters.
3. You may use either the MySQL command line program on your web host's command line or a tool such as phpMyAdmin to create the Commute Calendar tables in your MySQL database. Login to MySQL using one of those tools and execute entire contents of tables.sql on your MySQL database.

Configuring The Web Application

Getting It Up And Running

1. Execute the SQL code in tables.sql on your MySQL database as described above.
2. Edit lib/db.php to correspond to your database's credentials and location.
3. 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 variables at the top of lib/recaptchalib.php.
4. Make sure that all files in the cronjobs directory have been uploaded to a non-web-accessible directory on your web server, and are chmod 700, except for db.pl which should be chmod 600.
5. Edit the cron jobs contained in the crontab.txt file to correspond to their path on your web server, and then enter them into cron (from the command line, this is done with crontab -e).
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

• The HTML headers (top portions of pages) that appear on the tops of the pages of Commute Calendar are set in lib/headfoot.php. In this file, there are separate headers for authenticated PHP programs (pagehead function) and public PHP programs (publicheader function).
• Here is a listing of the header and footer files that correspond to other PHP programs that do not use lib/headfoot.php. The names of the header and footer files correspond roughly to the top level directory in which their parent program resides.
  • lib/login_head.html is used by auth/index.php.
  • lib/reset_head.html is used by programs in the reset/ directory.
  • lib/share_head.html and lib/share_foot.html are used by programs in the share/ directory.
  • lib/foot.html is used all other public (non-authenticated) PHP programs, and lib/private_foot.html is used by PHP programs beyond the login point (authenticated).
• The administration section of Commute Calendar uses files in the lib/admin/ directory for the header, footer, and text that appears on the pages.
• The "share toolbar" (Facebook, Twitter, and other links) throughout the application are controlled by one convenient file, lib/share_bar.php.

Troubleshooting Tips

• Set appropriate permissions for your files. HTML and PHP files should be chmod 644, all directories should be 755, cron scripts should be 700, and db.pl in the cronjobs directory should be 600.
• You can try running your cron job scripts directly from the command line (type ./somescript.pl) to verify that they aren't producing any errors.
• You can try running PHP programs directly from the command line (type php someprogram.php) to verify that they aren't producing any errors (PHP Notices are usually ok, however).

For More Information