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.
- Edit
app/lib/db.pl to correspond to your database's credentials and location.
- Edit
app/lib/php/db.php to correspond to your database's credentials and location.
- 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.
- 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 .
- 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.
- 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.
|