3Deearts design

3DeeArts Calendar Version 3.0

Upgrade Guide


3DeeArts calendar version 3.0 Documentation

Upgrade Guide

3DeeArts Design

75 Maddock Ave. West Victoria BC Canada V9A-1E6

Email: sales@3deearts.com

Date: 2003-11-16

 




Version 3.0 is finally here!

Thank you very much for purchasing our product. It has taken many hundreds of hours of work to bring this release to you, and we hope you can have as much enjoyment using it as we did building it.

Thanks to all our friends, colleagues and customers for their help and feedback. We encourage users of this and other 3DeeArts products to send in feedback and feature requests so we can improve and add to our software for future updates.


System Requirements

To install the 3DeeArts Calendar on your web server, you must have the following:

Perl 5.004 or higher - Most web servers have Perl installed, but check with your technical support to make sure before you try installing. Your Perl version must also include some standard Perl libraries like CGI.pm, flock, cwd etc. Since these are standard with all Perl installations now, there should be no problem.

CGI Access - You must have the ability to run CGI scripts on your web server, usually from a folder called cgi-bin.

FTP Access - You must have the ability to FTP to your web server so that you can upload the necessary files, or have direct access to your server.

sendmail for Unix, SMTP for Windows - To utilize the email features of the 3DeeArts Calendar you must have the standard UNIX sendmail program available. For Windows, there is now email support for either SMTP, Net::SMTP or IO::Socket.

CRON job or task scheduler To make the reminders program function you need to be able to add it to a scheduling program like CRON on Unix./Linux or task scheduler on Windows. Please check with your tech support to see if this is available. If it is not, you can disable the reminders options in the program.

2.0MB of disk space - The total amount of space needed is entirely dependent upon how many people will be using the calendar and how much information is posted but we recommend at least 2MB.


Installation

Step 1: Unpacking

After downloading the file from our server you must first unpack the archive. The standard programs for unpacking are WinZip under Windows and Gunzip and Untar under Unix. Copy the archive file appropriate for your operating system into the cgi-bin directory of your web server or a temporary directory on your personal computer. Next:

Under Unix

1.      Gunzip the file. To do this type gunzip 3dacalendar30.tar.gz

2.      Untar the file (tar is a way of keeping associations and directories intact) by typing tar xfv 3dacalendar30.tar

Under Windows

1.      Double click on the archive name, or run WinZip.

2.      From WinZip open 3dacalendar30.zip and choose the extract action.

3.      Extract the archive to the desired location.

Now that you have unpacked the archive, a new directory called 3deearts_calendar will be in your directory structure. In its sub-directory Install_files the files listed in step 2 should be present.

After unpacking your files, you need to make sure that the first line in the files calendar.cgi, install.cgi and remind.pl is the correct path to Perl 5 on your server. This is usually #!/usr/bin/perl on Unix servers. If you do not know the path to Perl on your server, contact your hosts support and ask them. The default is usually ok.

The files calendar.cgi and install.cgi may have to be changed to extensions .pl if your server only supports the .pl extension. Some Windows NT servers run this way. It is safe to rename them if you need to.

If you need to rename the file install.cgi to install.pl open the file in a text editor and change line 38 where it says: my $ext = 'cgi'; change it to my $ext = 'pl';

If you are using FTP to upload files, make sure that you upload all the files in ASCII mode when needed. This is specified in the file list below. Most modern FTP-Clients know what to do themselves, but it's still recommended that you check if it really uploads everything in ASCII by setting this in your FTP programs options.

For example: In the program CuteFTP by GlobalSCAPE Inc, go to File then Transfer Type and choose either Auto, ASCII or Binary.


Step 2: Preparation

To safely prepare your existing calendar to be upgraded please follow these instructions carefully.

Prep 1) IMPORTANT! Make a backup copy of your calendar files on your server. We recommend you download them to your local computer and store them in a safe place. NOTE: Do not make a backup of the sessions directory or any files contained in it. It is not needed.

Prep 2) DELETE the following files and directories:

          contacts/private directory and all files in it

          contacts/aindex.txt

          sessions directory and all files in it

NOTE: Do not delete any files in the directories users or databases.

Prep 3) Copy the following files from the 3DeeArts Calendar 3.0 archive to your server in their correct directories listed above. If you are prompted to overwrite existing files with the new files please say yes. Check in the below files listing under the heading Version 3.0 File Structure for the correct permission settings for these new files and double check to make sure they are correct.

          calendar.cgi

          install.cgi

          remind.pl

          contacts/groups.txt

          data directory and all files in it

          languages directory and all files in it

          library directory and all files in it

          templates directory and all files in it

          users/altusers.db

          users/users.db

Prep 4) Replace all files from the HTML directory containing the sub-directories images and help.

Once finished the preparation, you can move onto the next step.


Step 3: Version 3.0 File Structure

Here is a listing of all the files contained in the version 3.0 archive. Please read above to know which files to upload. NOT all files should be uploaded, only those listed above under the heading Preparation - Prep 3.

CGI-BIN Directory (All these files should be uploaded in ASCII mode). Files requiring permission changes are highlighted in bold.

1 calendar - Root Directory (rwxr-xr-x) (755)

1 contacts - Sub-directory (rwxrwxrwx) (777 - full access)

2       .htaccess (644) (dont change permission)

2       counter.dat (rw-rw-rw-) (666 - full access)

2       groups.txt (rw-rw-rw-) (666 - full access)

1 data - Sub-directory (rwxr-xr-x) (755)

2       .htaccess (644) (dont change permission)

2       categories.txt (rw-rw-rw-) (666 - full access)

2       flood.txt (rw-rw-rw-) (666 - full access)

2       groups.txt (rw-rw-rw-) (666 - full access)

2       icons.txt (rw-rw-rw-) (666 - full access)

2       installer.txt (rw-rw-rw-) (666 - full access)

2       language.txt (rw-rw-rw-) (666 - full access)

2       news.txt (rw-rw-rw-) (666 - full access)

2       settings.pl (rw-rw-rw-) (666 - full access)

2       stats.txt (rw-rw-rw-) (666 - full access)

2       style.txt (rw-rw-rw-) (666 - full access)

1 databases - Sub-directory (rwxrwxrwx) (777 - full access)

2       .htaccess (644) (dont change permission)

2       counter.dat (rw-rw-rw-) (666 - full access)

1 languages - Sub-directory (rwxr-xr-x) (755)

2       .htaccess (644) (dont change permission)

2       English.lng (644) (dont change permission)

1 library Sub-directory (rwxr-xr-x) (755)

2       .htaccess (644) (dont change permission)

2       admin.pm (644) (dont change permission)

2       backup.pm (644) (dont change permission)

2       colors.pm (644) (dont change permission)

2       contact.pm (644) (dont change permission)

2       date.pm (644) (dont change permission)

2       decode.pm (644) (dont change permission)

2       direct.pm (644) (dont change permission)

2       event.pm (644) (dont change permission)

2       login.pm (644) (dont change permission)

2       mail.pm (644) (dont change permission)

2       members.pm (644) (dont change permission)

2       options.pm (644) (dont change permission)

2       search.pm (644) (dont change permission)

2       select.pm (644) (dont change permission)

2       setup.pl (644) (dont change permission)

2       smilies.pm (644) (dont change permission)

2       subs.pm (644) (dont change permission)

2       views.pm (644) (dont change permission)

1 logs Sub-directory (rwxr-xr-x) (755)

2       .htaccess (644) (dont change permission)

2       ip_log.txt (rw-rw-rw-) (666 - full access)

2       remind_log.txt (rw-rw-rw-) (666 - full access)

2       reminders.txt (rw-rw-rw-) (666 - full access)

1 templates Sub-directory (rwxr-xr-x) (755)

2       .htaccess (644) (dont change permission)

2       template.html (644) (dont change permission)

1 users Sub-directory (rwxrwxrwx) (777 - full access)

2       .htaccess (644) (dont change permission)

2       admin.dat (rw-rw-rw-) (666 - full access)

2       altusers.db (rw-rw-rw-) (666 - full access)

2       users.db (rw-rw-rw-) (666 - full access)

2       calendar.cgi (or calendar.pl) (rwxr-xr-x) (755)

2       index.html (644) (dont change permission)

2       install.cgi (or install.pl) (rwxr-xr-x) (755)

2       remind.pl (rwxr-xr-x) (755)

 

HTML Directory (no need to explicitly set permissions for any of these files, leave as default) (upload type of Binary or ASCII is noted beside each file type)

1 calendar - Root HTML Directory

1 help - Sub-directory

1 images - Sub-directory

2       All .gif and .jpg image files (upload in BINARY)

2       index.html (upload in ASCII)

2       All .html files (upload in ASCII)

1 Images and all sub folders (admin, icons, level, menu, smilies)

2       All .gif and .jpg image files (upload in BINARY)

2       index.html (upload in ASCII)

 

The files and folders in the HTML directory in the above directory tree are meant to be put outside of your cgi-bin directory. It is recommended to create a directory in your main web directory called calendar as it is above. In this directory there will be the two sub-directories called help and images as above. Do not change the names of help or images. Transfer all the files into their associated directories on your server keeping the structure the same. Remember where you put them.


Step 4: Permissions

Setting Permissions in Unix/Linux

You need to set permissions manually using an FTP program, and it is quite easy. The file permissions that need to be set for each file are listed above to the right of each directory or file name in the directory structure list, under CGI-BIN Directory All files listed as (Do not change permission) should be left as the default setting your server uses when you upload them. To set permissions manually, here are some images from a Windows FTP program for quick reference with their associated number values. Some FTP programs allow to directly input number values as well.

666:

777:

755:

Note

Not setting permissions correctly is the NUMBER ONE reason that users have problems during or after installation. Please take extra care to make sure all the files have the correct permissions.

Setting Permissions in Windows

Windows NT/2000 servers do not allow users to change permissions remotely through FTP. Windows permissions can be set only at the console, so the administrator must physically sit down in front of the computer and use the Explorer interface to click on the desired directories and set the desired permissions.

Customers of web hosts

If you are not the administrator of your Windows server, the only way to have permissions changed for you is to contact your technical support. Here is a sample e-mail that you can modify and use for that purpose:

Dear Support Staff:

To complete the installation of a Perl software package
on my site, I need permissions changed for the following:

*
{Input permissions as noted above with correct path}

Please let me know when these changes are completed.

Sincerely,
{Your Name}

* Also include your host server number, site user name and any other information you think they might need to complete these changes.

If you are the administrator

If you administer your own server, set permissions using the Windows explorer interface according to the instructions above in the file structure listing. At minimum, you should make all files marked full access above have full access (ie. give "Full Control" access to "Everyone" in those directories or you can also choose to set them to Change). The following screen shot demonstrates the setting of permissions on Windows NT:

Step 5: Running the Installer for Upgrading

After your upgrade preparations are complete, you will need to complete the upgrade by running the installer program. Type the URL to the installer in your internet browser.

For example: http://www.mysite.com/cgi-bin/calendar/install.cgi

The installer welcome screen will appear. Just follow the step by step instructions and input the correct information until the installer is completed your upgrade. When asked by the installer, please choose Upgrade from Version 2.0 and NOT New Installation. After the upgrade has completed use your previous User ID and Password to log into the calendar:

To edit your calendars settings go to the admin menu option at the top of the screen and from there go to calendar settings and you see a much larger list of settings for you to modify if you choose.

Congratulations, you now have completed your calendar upgrade!


Extras: Installing reminders

To take advantage of the reminders functionality of the calendar software you need the ability to set a cron job on your server if it is a Unix/Linux server or schedule the program in the task manager or any other method you know of in Windows. What is a cron job? A cron job is a method of making a program run by itself at a certain time interval. So you can make the program remind.pl run every hour by itself with no user input. This is how reminders work. The program runs by itself and looks for events coming up that need reminders sent. If it finds them, it sends out an email to each user in the list. To correctly install the program remind.pl, your server must have or give you the ability to edit a file that does this automated program running. Ask your technical support what to do as every server can be different in this department and some may not allow you to use this functionality.

To make it work in Unix/Linux you need to add a line to the cron tab that looks like this:

0 * * * * (cd /path to calendar folder && ./remind.pl)

where path to calendar folder is the path from the root to your calendar directory that the file remind.pl is located in. This configuration will run the program once an hour, which is exactly what we want.

NOTE: It is important to run the program only once an hour, or your users will receive multiple reminders for the same event.

We recommend you save this line to an empty text file. It does not matter what you call the file.  You should name it something so you remember what the file is (eg:  mycrontabfile).

Upload the file to your server as an ASCII file. Remember where you put it.

telnet into your server using a program like PuTTY and run the crontab file by going to the directory containing the crontab file and type the following:

         cd /path/to/mycrontabfile/directory

         crontab mycrontabfile

 


Additional Resources

Online Help

For installation tips or troubleshooting please visit the support and forum sections of our web site at: http://www.3deearts.com

Support Email

To contact us by email, please send inquiries to: help@3deearts.com


Programming Credits

Lead Programmer/Developer/Designer/Project Manager:

Darrell Andersen

documentation and site design:

Darrell Andersen

3deearts support staff:

Adam Steffanick

Darrell Andersen

additional Acknowledgements:

Thank you to all of the people who helped and supported us during the development of this project. Thank you to current users of the 3DeeArts Calendar for your support.