IRC Collective Installation Guide


Getting help
============

If you encounter any problems during the installation procedure, please do not
hesitate to ask for help on the IRC channel, the forums or the mailinglist.
But before you do, please make sure you have searched for an answer and have
read this document completely.


Contents
========

* Requirements
* Installing the parser
* Installing the database
* Installing the web application
* Troubleshooting
* Appendix A: Automate parsing using cron
* Appendix B: Notes on logfiles


Requirements
============

You need the following software installed and working before you can
continue:

-Perl
-Apache
-MySQL (or PostgreSQL or SQLite)

The following Perl modules must also be installed:

-DBI
-Digest::MD5
-CGI
-Date::Calc
-File::stat
-GD
-GD::Image::Thumbnail
-Getopt::Long
-HTML::Entities
-LWP
-POSIX
-Syntax::Highlight::Universal
-URI
-URI::Find

And either one of the following:

-DBD::mysql (for MySQL)
-DBD::Pg (for Postgresql)
-DBD::SQLite (for SQLite)

You will find that some of these modules are already present on your machine
if Perl is already installed.

Installing Perl modules can be done using the CPAN shell.

For example, type:

cpan -i Date::Calc

to install Date::Calc on your machine.

Alternatively, you can download those Perl modules from the CPAN website at:

http://search.cpan.org/

Make sure you have installed all the necessary prerequisites before you
continue.


Installing the parser 
=====================

If you haven't already, download the latest version from the website:

~$ wget http://ftp.irc-collective.org/files/irc-collective-0.1.4.tar.gz

The next step is to extract the archive:

~$ tar xvzf irc-collective-0.1.4.tar.gz

This will create a new directory called 'irc-collective-0.1.4'.

Change dir into this directory.

~$ cd irc-collective-0.1.4
~/irc-collective-0.1.4$

Create a new configuration file like this:

# IRC Collective configuration file
#[parser]

# The name of the channel
channel=collective

# The location of the logfiles (with trailing slash)
directory=/home/irc/irclogs/

# The format of the logfiles
input-format=Eggdrop

# The output handler to use
output-handler=SQL

#[sql]
# Details needed to connect to the database
dbname=irc_collective
dbtype=mysql
dbhost=localhost
dbuser=irc
dbpass=secret

#[images]
# The location on the filesystem where to store the local
# copies of the images fetched from the web
imagedir=/var/www/images/collective/

Save it in the conf/ directory.


Installing the database
=======================

This part of the installation will use MySQL as an example, but database
schema's for PostgreSQL and SQLite are also provided with the distribution.

Connect to the database server using an account that can create new databases:

~/irc-collective-0.1.4$ mysql -u username -p

This will enter the mysql CLI:

mysql>

Now create the database:

mysql> create database irc_collective;

Grant permission to the account that will be used to query the database:

mysql> grant all on irc_collective.*
    -> to 'irc'@'localhost'
    -> identified by 'secret';

Type quit to leave the CLI:

mysql> quit

The tables are defined in the *.sql files inside the ./db directory.

Create the tables by typing:

~/irc-collective-0.1.4$ mysql -u username -p database_name < db/create.sql

For SQLite and PostgreSQL: see `man sqlite3` and `man psql` respectively.


Installing the web application
==============================

The web application has been implemented as a CGI application. The scripts
are written in Perl and make extensive use of the CGI.pm module.

Copy the scripts to a directory inside the cgi-bin, like so:

~/irc-collective-0.1.4$ mkdir /usr/lib/cgi-bin/collective
~/irc-collective-0.1.4$ cp -R cgi-bin/collective/* /usr/lib/cgi-bin/collective

You Apache configuration file should have something like this:

ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/
<Directory "/usr/lib/cgi-bin">
    AllowOverride None
    Options ExecCGI -MultiViews +SymLinksIfOwnerMatch
    Order allow,deny
    Allow from all
</Directory>

Copy the contents of ./htdocs/images to your /var/www/images directory:

~/irc-collective-0.1.4$ cp -R htdocs/images/* /var/www/images

Now edit the configuration webapp.conf like so:

#[database]
dbname=irc_collective
dbtype=mysql
dbhost=localhost
dbuser=irc
dbpass=secret

#[images]
localcopy=/var/www/images/collective
image_baseurl=/images/collective

Now open http://yoursite/cgi-bin/collective/index.pl to see if it works.


Troubleshooting
===============

TODO


Appendix A: Automate parsing using cron
=======================================

This section will show you how to add the parser to the system scheduler.

On most linux installation you can schedule a command using cron.

You need permission to install a crontab, see `man crontab` for more
information.

Create a crontab.user file in your home directory, where user is your
username. Open the file in an editor and add a line similar to the one below:

10 * * * * * $HOME/collective-0.1.4/parselog --with-config=conf/your.conf \
--today

This will parse the current logfile every ten minutes.

Please note that I've used \ to wrap the command around two lines.

Install your crontab using:

crontab crontab.user

Check if your crontab has been installed using:

crontab -l


Appendix B: Notes on logfiles
=============================

Your logfiles must all be saved using the following layout:

#channel.log.20070821

Where channel is the name of your channel and 20070821 corresponds
with August 21th, 2007.

Below are the commands you can use to set up your IRC client to
enable logging in a format that the parser will understand.

X-Chat
------

Type the following commands inside your X-Chat client:

/set irc_logging 1
/set irc_logmask = %n/%c.log.%Y%m%d
/set stamp_log = 1
/set stamp_log_format = %b %d %H:%M:%S

Irssi
-----

Type the following commands inside your Irssi client:

/set autolog on
/set autolog_path ~/irclogs/$tag/$0.log.%Y%m%d

Eggdrop
-------

Change the following settings accordingly inside your Eggdrop configuration
file:

logfile jpk #channel "logs/#channel.log"
set log-time 1
set keep-all-logs 1
set logfile-suffix ".%Y%m%d"
set switch-logfiles-at 300

mIRC
----

From the main menu, click 'Tools', then 'options' (or press <alt>+o).

Open the 'IRC' node in the treelist, and  choose 'Logging'.

In the combobox 'Automatically log': choose 'Channels'.

Alter the Timestamp logs, so it looks like this (and therefore shows the 
time more accurate): [HH:nn:ss].

Make sure no stripping or trimming is enabled.

Uncheck 'Include network'.

In the 'Date filenames' combobox, choose 'by Day'.