-------------------------------------------------------------------- Chico Digital Web Tool 1.02 -------------------------------------------------------------------- Copyright (c) 2002 Alan Raetz, Chico Digital Engineering http://www.chicodigital.com support@chicodigital.com ---------------------------------------------------------------------- INSTALLATION OVERVIEW ---------------------------------------------------------------------- PLEASE READ THESE INSTRUCTIONS COMPLETELY. Setting up Web Tool requires knowledge using FTP, HTML, and some knowledge of Perl or previous experience setting up Perl/CGI scripts. Your web hosting account must support CGI scripts (have a cgi-bin). The main configuration is done by an automated web-based installation script that runs the first time run the main program (webtool.cgi). When you run the webtool.cgi script for the first time, it creates the configuration file cgi-bin/WebTool/Config/wtConfig.pm, which can be manually edited at any time after the initial install. Most other customization can be done by modifying the Perl module cgi-bin/WebTool/Customize.pm or WebTool/Variables.pm. Email any questions to support@chicodigital.com. An overview of how to create template files is in the Administrator's Guide, in www/WebTool/docs/AdminGuide.html. There are separate install instructions for Unix and NT-based servers. Skip the Unix section if you are on a NT/2000 Windows server. See the TROUBLESHOOTING section below if you're having problems. --------------------------------------------------------------------- USING .htaccess FOR PASSWORD PROTECTION --------------------------------------------------------------------- We STRONGLY recommend that you use a password protection scheme to prevent anyone from accessing the editor from the internet. Although it may seem that 'no one will know' where the webtool.cgi script is, this application is generally installed in the default location: http://yourSite.com/cgi-bin/WebTool/webtool.cgi Since spiders can search for this script name across the internet, it leaves those sites without password protection open to outside use by unauthorized persons. An easy way to add password protection for editor access is to setup your cgi-bin/WebTool sub-directory with the .htaccess protocol (as the demo does on the chicodigital.com site). Many web hosting accounts allow you to set up password protection of directories via a web browser-based interface (an account control panel). If you plan to run webtool.cgi without password protection, it is recommended you place it in a directory within cgi-bin, but not as cgi-bin/WebTool/webtool.cgi. For example, put it in cgi-bin/xk22YYfeov/webtool.cgi (a random directory name that only your authorized users know). Htaccess will prompt users to enter a name and password in order to access any file in the protected directory, including scripts such as webtool.cgi. There are many tutorials on the web regarding setting up the .htaccess file on unix/linux web servers, just do a google search for .htaccess. Note that the actual password file should not exist within a directory that is web-accessable, if at all possible. .htaccess supports access groups and so adding new users is a 1-line shell command (you must have shell/SSH access to your web server). Another option for password protection are free password protection scripts such as those found in: http://cgi.resourceindex.com/Programs_and_Scripts/Perl/Password_Protection/ DC_protect98 and Protect.pl seem to be well-suited, however, we have not tested any of these products with Web Tool, and do not support any of them. ------------------------------------------------------------------------ UNIX INSTALLATION PROCESS ------------------------------------------------------------------------ This describes how to install this application on a UNIX / Linux / BSD / MacOS-X web server. Some of the details assume: - You've downloaded the entire Web Tool package and unzipped it on your local Windows machine. - You have an FTP client that will remotely connect with your linux/unix/BSD-based web server account. Note that this package can be installed many other ways; for example, the package .tgz file can be directly downloaded onto the server and unzipped there (if you have SSH or shell access). ------------------------------------------------------------------------ UNIX STEP ONE: Fix File/Directory Permission Issues ------------------------------------------------------------------------ Modify the top of cgi-bin/WebTool/webtool.cgi to point to the path of your Perl executable (ie, #!/usr/bin/perl ). Set the file permissions on webtool.cgi to allow it to be executable. Change the write permissions on these two directories to allow them to be writeable by the web server. cgi-bin/WebTool/Data cgi-bin/WebTool/Config If the web pages that Web Tool creates will be in a subdirectory of your main site, you need to create that directory and set the permissions to make it writeable by the web server. The default config uses this directory: /users/home/yourSite.com/webt/ ------------------------------------------------------------------------- UNIX STEP TWO: Copy all files and directories using your FTP client. ------------------------------------------------------------------------- Part A) Copy cgi-bin/WebTool to your cgi-bin/WebTool. Part B) Copy www/WebTool to YourWebDirectory/WebTool. Details: Go to your cgi-bin directory on the server using FTP. Highlight your local cgi-bin/WebTool and copy it over using 'text' mode (do not use 'binary' mode). This should copy all files within the directory and create all subdirectories. If your FTP software doesn't support this, manually create all directories and copy all files (file and directory names are usually case sensitive). Go to your web-accessable directory. This may be your base directory, or it may be the www/ or htdocs/ sub-directory. See your web server account information or server documents. Highlight your local www/WebTool and copy it over. This should copy all files within the directory and create all subdirectories. If that doesn't work, manually create all directories and copy all files. Note you will need to copy the .gif and .jpg files manually using 'binary' mode if your FTP client does not support auto typing. Here is the default cgi-bin directory structure: cgi-bin | WebTool | ------------------------------------------------------------- | | | | | Data WebTool ChicoDigital Config webtool.cgi | | | | .pm FormMethods.pm LinkMethods.pm wtConfig.pm etc. etc. .pm is the Perl database file. wtConfig.pm is the Web Tool configuration file. Note that if the directories are manually created using your FTP client, files and directory names are case sensitive (capitals and lower case must be copied exactly). The integrity of all the Web Tool cgi-bin files is automatically checked when the setup script is executed. --------------------------------------------------------------- UNIX STEP THREE: Run webtool.cgi from your web browser --------------------------------------------------------------- Type in the web address of the Web Tool script into your web browser: (for example) http://yourSite.com/cgi-bin/WebTool/webtool.cgi The first step will check that Web Tool can run on your server without modification. Click on submit and you should see the Configuration Form. If you get an error, follow the instructions on manually editing the Setup.pm file. The next screen will ask you to specify your web account path and URL information. Follow the instructions carefully and hit submit. NOTE: This form asks for two types of path information; be sure you understand the difference. If the form asks for a web address URL, that entry would be the address that a web user would type into a web browser to access that file or directory. If the form asks for a "full directory path", that entry is the file directory path on your web server. Both these path types to the different directories should be provided by your web hosting service provider. The script will then use the path information you specified and check that the required application files exist. It will check to see that the Config and Data directories to be writeable by the web server user process. Fix any problems shown. If you are not installing files in the default locations, you may choose to ignore these warnings. If you click 'Create Config File' the config file will be written. You should now be able to re-run webtool.cgi and get the main web page editor application to appear. You may need to manually edit the Config/wtConfig.pm file. Note that the automated web installation simply creates this config file. Any manual edits will have the same effect; the only exception is the BASE_TITLE. The setup script writes the initial database file using the BASE_TITLE entry. If you change the BASE_TITLE, you must also rename and edit the cgi-bin/WebTool/Data/.pm file. You cannot simply rename this file; you must also edit the declaration at the top of the file, "package Data::;" Change this entry to your new BASE_TITLE. Any changes should be immediately recognized the next time webtool.cgi is run. An overview of how to create template files is in the Administrator's Guide, in www/WebTool/docs/AdminGuide.html. ------------------------------------------------------------------------ END OF UNIX INSTALL ------------------------------------------------------------------------ ------------------------------------------------------------------------ WINDOWS NT/2000 INSTALLATION PROCESS ------------------------------------------------------------------------ ------------------------------------------------------------------------ NT/2000 STEP ONE: Fix File/Directory Permission Issues ------------------------------------------------------------------------ Set the first line of webtool.cgi to the Perl executable; follow your web server instructions, usually something like: #!c:\perl\bin\perl.exe If required by your web host, rename the script from webtool.cgi to webtool.pl. You only need to rename the file webtool.cgi. The other Web Tool files in cgi-bin that end in '.pm' should not be renamed. Some web hosts do not allow perl scripts to write files by default. If you get a 'Permission denied' message at any point during the installation, contact your technical support and request that your Perl scripts be given write permission within your directory. ------------------------------------------------------------------------ NT/2000 STEP TWO: Copy files to server ------------------------------------------------------------------------ Most NT servers allow you to execute scripts from any web-accessable (www) directory. If this is the case, create a cgi-bin directory inside your www directory: www/cgi-bin. Copy the Web Tool CGI file into that directory so you have this directory structure: www/cgi-bin/WebTool/webtool.cgi (the main script) www/cgi-bin/WebTool/WebTool/FormMethods.pm (and all other files from cgi-bin/WebTool/) www/cgi-bin/WebTool/ChicoDigital/LinkMethods.pm (and all other files from cgi-bin/ChicoDigital/) www/cgi-bin/WebTool/Config/* www/cgi-bin/WebTool/Data/* ------------------------------------------------------------------------ NT/2000 STEP THREE: Run webtool.cgi from your web browser ------------------------------------------------------------------------ Type in the web address of the Web Tool script into your web browser: (for example) http://yourSite.com/cgi-bin/WebTool/webtool.cgi The first step will check that Web Tool can run on your server without modification. Click on submit and you should see the Configuration Form. If you get an error, follow the instructions on manually editing the Setup.pm file. This will ask you to specify your web account path and URL information. NOTE: This form asks for two types of path information; be sure you understand the difference. If the form asks for a web address URL, that entry would be the address that a web user would type into a web browser to access that file or directory. SPECIAL NOTE FOR NT SERVERS: Do not use the full path for file directories; in general, this doesn't seem to work. All path information should start with a './' from your root account directory. For example: CGI_PATH => './cgi-bin/WebTool/', HOME => './WebTool/', CONTENT_DIR => './webt/', ALSO: If you install the cgi-bin/WebTool files in a directory other than cgi-bin/WebTool, you probably need to change the following statement at the top of webtool.cgi: BEGIN { push(@INC,'./cgi-bin/WebTool'); } Change the path so that it points to the directory where webtool.cgi is. The script will then use the path information you specified and check that the required application files exist. It will check to see that the Config and Data directories to be writeable by the web server user process. Fix any problems shown. If you are not installing files in the default locations, you may choose to ignore these warnings. If you click 'Create Config File' the config file wil be written. You should now be able to re-run webtool.cgi and get the main web page editor application to appear. --------------------------------------------------------------------- END OF WINDOWS NT/2000 INSTALL PROCESS --------------------------------------------------------------------- --------------------------------------------------------------------- TROUBLESHOOTING INSTALL PROBLEMS --------------------------------------------------------------------- These are some commonly reported problems when installing Web Tool. Please pay attention to the actual error message that shows up in your browser window. Yes, it really means something. These errors are listed in the order they would appear (if you did everything wrong): ----------------------------------------------------------------------- Browser shows a "Internal configuration error" or "Internal Server Error" when running webtool.cgi from a web browser. ----------------------------------------------------------------------- 1) If this is the first error you get, then it's probably because you didn't edit the top line of webtool.cgi to point to the correct path of the Perl executable, for example, on unix/linux/BSD systems: #!/bin/perl or #!/usr/bin/perl or #!/usr/local/bin/perl on windows systems, this is typical (notice the slash direction): #!c:\perl\bin\perl.exe You need to get this information from your web adminstrator or hosting service technical support. The path is often included in the email sent to you when you open a web hosting account. 2) The other common problem is that the webtool.cgi file has not been set as executable (CHMOD 755). You set files as executable using your FTP client. Typically you select the file and there should be an option to change the file permissions. You need to check the 'execute' box to allow anyone (everyone) to execute the file. ----------------------------------------------------------------------- "Could not find module /.pm" message appears when running webtool.cgi from your web browser. ----------------------------------------------------------------------- 1) The main webtool.cgi script is unable to locate all the modules in the cgi-bin directory. You must install all the files in the cgi-bin directory of the distribution, and you must preserve the directory structure of the distribution. This means you must manually create the directories 'WebTool', 'ChicoDigital', 'Config', and 'Data' in the directory where webtool.cgi is running. Here is the default cgi-bin directory structure: cgi-bin | WebTool | ------------------------------------------------------------- | | | | | Data WebTool ChicoDigital Config webtool.cgi | | | | .pm FormMethods.pm LinkMethods.pm wtConfig.pm etc. etc. .pm is the Perl database file. wtConfig.pm is the Web Tool configuration file. Yes, it really needs all those files. No, they don't need to be set as executable. Yes, the directory and file names are case-sensitive on unix/linux servers. 2) All the files are there, but you still get the same error. You need to edit the top of your webtool.cgi file. Change the directory on this line: BEGIN { push(@INC,'./cgi-bin/WebTool'); } to point to the full path of the cgi-bin directory where webtool.cgi is, for example: BEGIN { push(@INC,'/home/users/myWebSite/cgi-bin/WebTool'); } 3) Still getting the above error message ("Could not find module")? You must be on a strange type of web server or platform. At this point, you're pretty much on you own (for this error type). I could help you on an hourly rate--and I wouldn't charge you anything if I was unable to get it to work. Email support@chicodigital.com. ----------------------------------------------------------------------- When running webtool.cgi from a web browser, the first configuration screen appears, "Test Script Path", but when you click on the button at the bottom nothing happens, or you get a browser error. ----------------------------------------------------------------------- You need to edit the top of the cgi-bin/WebTool/Setup.pm file. Read the instructions at the top of this file. ----------------------------------------------------------------------- You fill out the configuration form, but when you submit it, it reports errors. ----------------------------------------------------------------------- If it's reporting missing files, then either they have not been installed in the right location, or the directory path you're providing the program is incorrect. Look carefully at the error message and check to see if that file exists. Is the path wrong? Use the 'back' button on your web browser to return to the form (it will preserve your values) and edit the path information until you don't get any errors. Note that there is a set of files (templates and documentation) that MUST be installed in a web-accessable directory on your web server. This config script is checking that all these files can be located by the program correctly. The script is still reporting missing files at this point? If the script can not find files using the full directory path, you can also use relative directory addressing, for example: CGI_PATH => './' HOME => '../../WebTool/' CONTENT_DIR => '../../webt/' On the above server, the root path (the '.') is relative to the cgi-bin directory the script is running in. On other servers, the root path '.' might represent the base directory of the web site, for example: CGI_PATH => './cgi-bin/WebTool/' HOME => './WebTool/' CONTENT_DIR => './webt/' Or maybe, just leave out the '.' altogether: CGI_PATH => '/cgi-bin/WebTool/' HOME => '/WebTool/' CONTENT_DIR => '/webt/' ----------------------------------------------------------------------- "Unable to write file " message in the Web Tool editor (after the installation has completed). ----------------------------------------------------------------------- You need to read the error message and make sure that the directory it is trying to access exists and is writeable by the web server. You need to set the permissions of the file using your FTP client or with a shell command. NT/2000 web servers run from hosting companies are very inconsistent about allowing the web server to write files. I think part of the problem is technical inexperience. They may say you can write files when you actually can't. Here's how to check for sure: take this code snippet and put it in a file 'writeTest.pl' and place this file in your cgi-bin directory on your server and run it from your web browser as a CGI script: #!c:\perl\bin\perl.exe my $directory = './cgi-bin/WebTool/Config/'; my $file = $directory . 'hello.txt'; print "Content-type: text/html\n\n"; print "Test of file write in perl
\n"; open(TEST,">$file") or die "

Couldn't write file $file, $@ $!
\n"; print TEST "hello there"; close(TEST); print "Wrote File hello.txt Okay!\n"; -------------- end of script ------------------ The above script tests if the cgi-bin/WebTool/Config is writeable. If the script shows an error message when you run it from your browser, that means the directory is not writeable. Send the URL to run this script to your tech support and tell them to run it. If this script continues to fail, and yet they say the directory is writeable, I'd recommend that you change hosting companies. Change the $directory variable of this script to check these directories: 1) your cgi-bin/WebTool/Config directory 2) your cgi-bin/WebTool/Data directory 3) the directory where you are writing your finished web pages (the CONTENT_DIR directory you specify in your wtConfig.pm). All three of these directories must be writeable by the web server for Web Tool to work. ==================== END OF INSTALL.TXT FILE =========================