==========================================================================
			INSTALL SHORT NOTICE
==========================================================================

This document is just a short notice for installation and may be outdated.
If you want a more detailed documentation, go to the /w3perl/docs/uk/
directory and use for browser to open the index file. 
Only HTML files are provided.

1) - SECURITY
2) - UPGRADE
3) - INSTALL
   A] cgi-bin and ssh
   B] no cgi-bin but ssh
   C] cgi-bin without ssh (FTP on a provider)
   D] Windows users
   E] RPM
   F] Debian
   G] No server
   H] Advice
   I] No logfile

1) - SECURITY
=============

Don't forget to password protect your admin directory with an htaccess
file or anyone will be able to change your configuration file or run
the stats for you. You can also add your IPs in the /admin/pass.txt
file if php is available.


2) - UPGRADE
============

Download the latest w3perl package and untar it over your current
w3perl directory. Then just run the upgrade.pl script.
Will read your upgrade.txt file, update your configuration files and copy
the scripts into your cgi-bin directory.


3) - INSTALL
============

W3Perl need to read logfiles, so you can install w3perl :
3-1) on your server where the logfiles are located
3-2) on a local host if the logfiles can be retrieved from your server
3-3) on a local host if your logfiles have been downloaded there.
3-4) on a local host if you have no access to your provider's logfiles.

3-2 :
Note that logfiles can be retrieved remotely; w3perl is able to
download them (wget) before processing allowing you to install w3perl on a
separate host from the server. If so, logfiles should be available
from an URL, hidden and password protected from the world.

3-3 :
If not and still you want to process locally your stats, you can always download
manually the logfiles on your own hosts and install w3perl locally.

3-4 :
Note that W3Perl can generate logfiles in you have no access to your provider logfiles.
You need to include a small javascript into your web page and a daily logfile will
be created (see documentation for more information). Then download them on your host and
W3Perl will be able to report stats.

A] INSTALLATION FOR UNIX USER (cgi-bin and ssh)
-----------------------------------------------

<webdir> is your server root directory
<w3perldir> is the location where the w3perl package have been extracted

1) Extract the package inside your web server tree

cd /<webdir>/htdocs/
tar -zxvf w3perl.tar.gz
/<webdir>/htdocs/w3perl/ will be created (<w3perldir>)

2a) If you feel lucky, you can run 'install.pl -a' which will try
to install the package reading your Apache configuration file (root user need)

2b) Or edit the install.pl script and setup three variables

a) the first line is your Perl path
b) $pathcgi is the directory where the w3perl script will be placed : /<webdir>/cgi-bin/w3perl
c) $pathw3perl is the directory where the w3perl package have been extracted
(the directory where you are are reading this file from) : <w3perldir>

3) Run install.pl
If you don't want to run this script as root, create manually the $pathcgi (usually
as root as cgi are root owner). Change owner to yours (chown -R <user>: $pathcgi).
Then run the install.pl script as a user.

4) Launch web interface

Use your browser and go to http://localhost/w3perl/admin/
Select 'Make configuration files' (use default 'config' for filename)
Fill the different forms..
You will have to move the configuration file you have built
from <w3perldir>/config/<configfile> to 
/<webdir>/cgi-bin/w3perl/<configfile>
Template are available to make things easier. For instance, if you are on
Ubuntu, choose the 'Clone' option and select the ubuntu default configuration
file, then just modify the values you want to alter. 

5) Compute stats

Run first cron-pages.pl either from command line or from the admin interface.
(Use your browser and go to http://localhost/w3perl/admin/, Select 'Launch scripts', 
Click on 'First Run').
To avoid reading all your logfiles, use the -d flag to select only a few days.
If no error is reported, run the init script : 'cron-w3perl.pl -a' which will compute
everything foy you. If you are using another configuration than the default one (config.pl)
add the -c <your_configfile>.
=> cron-pages.pl -d 5 (to get stats for the last 5 days)
=> cron-pages.pl -c config_myserver.pl -d 5 (to use my own config file)

==========================================================================

B] INSTALLATION FOR UNIX USER (ssh without cgi-bin)
---------------------------------------------------

<webdir> is your server root directory
<w3perldir> is the location where the w3perl package have been extracted

1) Extract the package inside your web server tree

cd /<webdir>/htdocs/
tar -zxvf w3perl.tar.gz
/<webdir>/htdocs/w3perl/ will be created (<w3perldir>)

2) Configuration files

User without cgi-bin access can't use the administration interface.
You'll have to make your configuration files by yourself.
cd <w3perldir>/config/
Inside you'll find some default configuration files, edit and
modify it with your own values. If you have some problem, you can
read the documentation or ask for help in the forum.
An online tool is available at http://www.w3perl.com

3) Compute stats

Run first cron-pages.pl to check everything is ok.
To avoid reading all your logfiles, use the -d flag to select only a few days.
If no error is reported, run 'cron-w3perl.pl -a' which will compute
everything foy you.
=> cron-w3perl.pl -d 5 -a (to get stats for the last 5 days)
=> cron-w3perl.pl -c config_myserver.pl -d 5 -a (to use my own config file)

==========================================================================

C] INSTALLATION FOR UNIX USER (cgi-bin without ssh)
---------------------------------------------------

<webdir> is your remote server root directory
<local_w3perldir> is the location where the w3perl package have been extracted
<w3perldir> is the remote directory where the w3perl package will be installed
You'll have to use ftp to upload w3perl files.

1) Extract the package on your computer

tar -zxvf w3perl.tar.gz
<local_w3perldir> will be created 

2) Install w3perl files

	a) Create a /w3perl/ subdirectory in your remote server

FTP : cd /<webdir>/www/ or whatever your www directory is.
FTP : mkdir w3perl ==> <w3perldir>

	b) Put files

FTP : cd /<webdir>/www/w3perl
FTP : mput admin/*
FTP : mput config/*
FTP : mput docs/*
FTP : mput resources/*

	c) Permission

FTP : chmod 777 config
FTP : chmod 777 resources/admin

3) Install w3perl scripts files

	a) Create a /w3perl/ subdirectory in your remote cgi-bin

FTP : cd /<webdir>/cgi-bin/
FTP : mkdir w3perl

	b) Move all the scripts in this cgi-bin subdirectory

FTP : mput *.pl /<webdir>/cgi-bin/w3perl/
FTP : mput *.sh  /<webdir>/cgi-bin/w3perl/
FTP : mput  admin/scripts/* /<webdir>/cgi-bin/w3perl/

	c) Executable

Check all scripts are runnable. If not
FTP : chmod +x *.pl
FTP : chmod +x *.sh

4) Configure path

Use your browser and go to http://localhost/w3perl/admin/
Select 'Launch scripts'
Click on 'Customisation'
The list of files modified will be show.

5) Launch web interface

Go back
Select 'Make configuration files' (use default 'config' for filename)
Fill the different forms..
You will have to move the configuration file you have built
from /<w3perldir>/config/<configfile> to 
/<webdir>/cgi-bin/w3perl/<configfile>

--                                           --
---- If the above failed                  -----
---- Manual configuration                 -----
---- (but best is to use admin interface) -----
--                                           --

Example available in <local_w3perldir>/config/config-unix.pl
You will have to move it to <webdir>/cgi-bin/w3perl
Use config.pl filename for default configuration file.


6) Compute stats

Run first cron-pages.pl from the admin interface.
(Use your browser and go to /w3perl/admin/, Select 'Launch scripts', 
Click on 'First time')

==========================================================================

D] Windows users
----------------

a) Just run the :
   - w3perl-iis.exe (IIS server) 
   - w3perl.exe (no web server)
   - w3perl-apache.exe (Apache server)
   = w3perl-abyss.exe (Abyss server)
b) Before using the administration interface, be sure that the following 
   directories are writeable by the server :
   - /w3perl/ (if you want to launch stats via the admin interface)
   - /config/
   - /resources/admin/
c) go to the w3perl admin section http://localhost/w3perl/admin/
d) Use the provided iis/apache/abyss configuration file
e) Create a configuration file and move it to the /cgi-bin/w3perl directory
f) If you are using the web interface, make sure your logfiles are readable
by your IIS user (IUSR_[hostname])
g) make sure CGIPerl is enabled in 'Web Service Extension'
h) If you are using the web interface to run the stats, make sure cmd.exe
could be run from the IIS user (IUSR_[hostname]) or don't use
the master script (which fork w3perl's scripts).
i) make sure your logfile are readable by the IIS user
k) make sure your output directory will have write access

==========================================================================

E] RPM
------

a) download the fly rpm and rpm -i fly-1.6.5-1mdk.i686.rpm as root
b) download w3perl and rpm -i w3perl-3.15-1mdv.noarch.rpm as root
c) go to the admin http://127.0.0.1/w3perl/admin/ and alter the
'mandriva' configuration file if needed
d) run the stats either with the admin or using command lines

==========================================================================

F] Debian
---------

a) download the fly package and install it.
b) download the w3perl debian package and dpkg -i w3perl_3.15_all.deb as root
c) go to the admin http://127.0.0.1/w3perl/admin/ and alter the 'ubuntu'
configuration file if needed.
d) run the stats either with the admin or using command lines

==========================================================================

H] Advice
---------

a) Best is to use the admin interface to generate your configuration
file and to launch the scripts via ssh
b) First test with one small script : cron-hour.pl
c) If everything is OK, run cron-pages.pl for initialisation or
cron-w3perl.pl -a to compute everything.

==========================================================================

I] No logfile
-------------

If you do not have logfile access, you can add a javascript tag inside
each page you want to monitor. 

  a) Server side

Insert the javascript tag in your web pages (at the end of your web page, just before the
ending tag for body). Make sure the /w3perl/logs/ is writeable and
don't forget to password protect it.

  b) client side

Install w3perl locally. If you have a server running locally, use the
administration interface to build your configuration file. Select the
option to retrieve automatically your server's logfiles. If no web
server is running, edit the config-tag.pl file provided and change
parameters according to your own configuration.

