CalendarScript - Calendar Documentation: Installation/Setup

Quick Setup

If you are downloading to a Windows machine, and will then publish the script to your remote web server, the install processes is simplified by using the 'install.bat' batch file.

Download the .zip file to your Windows machine and unzip it. This should automatically create subdirectories containing many files which are needed by the calendar application. In the root of these folders you will find an 'install.bat' file. Go to a command-line and run this program.

To run this install routine, 4 parameters are required:

FTP Host Name: This is the server name that you will FTP into to upload your files
Username: The username to login to the FTP host
Password: The password of the above username
Install Directory: This is the directory where the files should be placed once the program logs into the server. This can be written as a full path, like /home/user/www/cgi-bin/ for example, or a relative path like www/cgi-bin/. It's very important that you consider the following:
- This directory must exist before running the install program
- Once the program is logged in using FTP, it will simply do a 'cd' to whatever directory to give.
- If you specify a full path starting with a / then make sure you have the right path. A path like /cgi-bin/ is most likely NOT correct. If you don't understand this, ask your web host.
- If you use a relative path, make sure it is relative to the default directory you are placed in when you login via FTP.

Once this program runs, it will use FTP to login to the server, transfer files, create directories, CHMOD files, etc. If your server doesn't support the CHMOD command or if there are any problems, you will need to follow the detailed install instructions below.

Download

Download either the .zip file or the .tar.gz file from http://www.CalendarScript.com/. The file contents are identical. The .tar.gz file is recommended for people downloading directly to a Unix computer, and the zip file is recommended for everyone else. The .tar.gz file contents are formatted with Unix-style newlines to run in a Unix environment. If you are unsure what any of that means, download the zip file to your local computer.

Uncompress the archive

To uncompress the zip file, using a utility such as Winzip on your local computer and extract the files to an empty directory on your drive. It should automatically create subdirectories containing many files which are needed by the calendar application.

To uncompress the .tar.gz file, use the tar and gzip utilities. It also will create the required directory structure.

Modify Perl Scripts

Two modifications might need to be done to the two perl scripts themselves (calendar.pl, calendar_admin.pl) to function on your server. Whether you need to do these depends on your answers to two questions in the 'Before You Begin' section.

A. Change the path to Perl5
If the path to perl on your web server is not /usr/bin/perl then you will need to open up each of the two files in a text editor and modify the very first line of the files. By default, these lines read:

#!/usr/bin/perl

If you know that your path to perl is different (ex: /usr/local/bin/perl5) then you should change this line to, for example:

#!/usr/local/bin/perl5

This must be the very first line in the file, and the #! are always required.

B. Change the file extensions
If your web server requires perl CGI scripts to have the extension .cgi, for example, then you should rename the two files to the new extension.

Transfer files to the web server

All the files and directories now on your local computer need to be transferred to your web server. The usual method to do this is via FTP. Using FrontPage is not recommended, as it has been known to cause problems with perl CGI scripts.

To FTP the files to your server, connect using a program such as WSFTP or CuteFTP. Navigate to the directory where your CGI perl scripts need to go, and transfer the whole directory structure to this location. Be sure to transfer all files in ASCII mode. If this is not done, file corruption could occur and the program could fail to operate. Once transferred to the web server, you should have calendar.pl and calendar_admin.pl in the CGI directory, and a subdirectory called 'calendarscript' beaneath that directory, containing all the rest of the files. Most good FTP applications will allow you to transfer a whole directory structure at once, automatically creating the necessary directories and putting files into the correct location. If your FTP program does not allow this, consider downloading one that will.

Modify file permissions

Once the files are transferred to the web server, the file permissions need to be modified. This allows for the perl scripts to be executable and for the data files to be writable by the application.

Depending on the operating system of your web server, you may need to take different actions to modify permissions on the files. Also, some web hosts do not allow users to change file permissions themselves. You may need to email your web host and tell them to perform the following permission changes, depending on your setup:

A. For Windows NT/2000 Web Servers
Windows does not require scripts to be set as executable, or write permissions granted via FTP. Instead, permissions on the file system itself must be setup to allow the application to write to the data fies. In Explorer, modify permissions on the 'calendarscript' directory and give 'Full Control' permissions on it and everything in it to 'Everyone'.

B. For Unix/Other Web Servers
File permissions must be set using your FTP program to allow the scripts to be executable and the data files to be writable. If your FTP program or web server does not support the CHMOD commands, see the note above about special web host guidelines.
File permissions must be set as follows:

calendar.pl = CHMOD 755
calendar_admin.pl = CHMOD 755
calendarscript directory and ALL FILES AND DIRECTORIES UNDER IT = CHMOD 777

Knowing how to set permissions on files is a requirement for setting up an CGI script. If these steps don't work or you need more information, search the web for 'ftp chmod' which will bring up many tutorials and sources of more information.

In some situations, web hosts do not allow files in or under the cgi-bin to be chmod 777, for security reasons. These are often situations where the scripts run as your own user ID, not as a user like 'nobody'. If you verify with your web host that this is the case for your site, then you should CHMOD 744 the 'calendarscript' directory and all files under it.

Run the Admin application

At this point, the aplication should be ready to run. To start the setup process, load the calendar.pl file in your web browser. The URL to it might look something like this:

http://www.yourserver.com/cgi-bin/calendar.pl

If the calendar does not display correctly see the next section, "Troubleshooting Installation." If it does display correctly, next check to make sure the calendar_admin.pl application is working. Load it in your web browser. The URL might look something like:

http://www.yourserver.com/cgi-bin/calendar_admin.pl

If the 'Setup Wizard' screen loads successfully, you are all set! You can continue to the Getting Started section. If there are any errors shown or if it doesn't work, please see the next section, "Troubleshooting Installation"