Quick start
===========

0 Find and install development files for: 

   g++ >= 3.2            - http://gcc.gnu.org/
   zlib                  - http://www.gzip.org/zlib/
   mimelib  (kdenetwork) - ftp://download.uk.kde.org/pub/kde/stable/latest/src
   xsltproc (libxslt1)   - http://xmlsoft.org/XSLT/
 
 If you need to, lurker can be built using only g++ 2.95, however 3.2+ is
 recommended as the resulting binaries are much smaller and faster.
 
 If you do not want kdenetwork, you can also download mimelib separately
 from http://sourceforge.net/project/showfiles.php?group_id=8168 and tell
 lurker to compile it and statically link to it.
 
 xsltproc is not strictly required for lurker. It is not used during compile
 and is only used if your lurker.conf references it. However, it is the
 preferred method for rendering html, so we recommend installing it.
 
 For debian: apt-get install xsltproc libmimelib1-dev g++ zlib1g-dev
 
1 [flags] ./configure [options]
  
  To control the mimelib location, setting these options may help:
  --with-mimelib-local        Use internal lurker/mimelib/*
  --with-mimelib-include=DIR  Location of mimelib/message.h
  --with-mimelib-libname=LIB  Try an alternative library name
  
  To control the zlib location, setting these options may help:
  --with-zlib-include=DIR     Location of zlib.h
  --with-zlib-libname=LIB     Try an alternative library name

  These settings also help control where lurker installs:
  --prefix=/usr               Put programs in /usr/bin and /usr/lib/cgi-bin
  --localstatedir=/var        Put db in /var/lib/lurker, web in /var/www/lurker
  --sysconfdir=/opt/local/etc           Put config files in /opt/local/etc/lurker
  
  --with-default-www-dir=/var/www/lurker  More specific control
  --with-default-config-dir=/opt/local/etc/lurker   Lurker finds config here by default
  --with-cgi-bin-dir=/usr/lib/cgi-bin     Place cgi programs in another spot
  
2 make

3 make install	(as root if you don't have permission)
  
  You may want to strip the binaries as they can be quite large.
  eg: strip -s /usr/lib/cgi-bin/*.cgi /usr/bin/lurker-*

  This will install these files:
  
  	(with-cgi-bin [/opt/local/lib/cgi-bin])/*.cgi
  		- The CGIs which power lurker
  		- These must be placed such that the webserver can run them
  	(default-www-dir [/opt/local/var/www])/*
  		- The lurker content which must be web accessible
  		- The subdirectories "attach, list, mbox, message, mindex,
  		  search, splash, thread, and zap" must all be writeable by
  		  whatever user executes lurker.cgi
  	(bindir [/opt/local/bin])/lurker-*
  		- Command-line utilities for importing email, cleaning
  		  cached web files, and interfacing with shell scripts
  	(localstatedir [/opt/local/var])/lib/lurker/*
  		- The lurker database directory where mail is imported to
  		- The directory and its contents must be writeable by the
  		  user who runs lurker-index
  		- This must be readable by the user who runs lurker.cgi
  
  If this is a new installation of lurker, try also: make install-config
  Then customize the template lurker.conf file.

  Make certain that lurker.cgi can modify /opt/local/var/www/lurker.
  If CGI programs run as www-data: chown -R www-data /opt/local/var/www/lurker
  
  Make certain that the CGI can read /opt/local/var/lib/lurker.
  Run 'lurker-index' with umask 002 to ensure it remains readable.
  
  lurker-index and lurker-prune (cronjob) modify /opt/local/var/lib/lurker.
  Make sure they have write access, but leave it accessible to the CGI.

4 Setup delivery of new mail to lurker-index
  
  For procmail and a simple one user install:
	:0 w
	* ^X-Mailing-List: <debian-japanese@lists.debian.org>.*
	| lurker-index -l japanese -m
  
  If you have a lurker group:
	Set 'db_umask = 002' in the lurker.conf file.
	chmod 02775 /opt/local/var/lib/lurker
  
5 Feed archived mail through lurker-index.
  
  lurker-index -l devel < debian-devel.mbox
  lurker-index -l devel -i debian-devel.maildir  
    
6 Setup a cronjob to update the archive every 15 minutes
  
  If you are installing lurker system-wide, put this in /opt/local/etc/cron.d/lurker:
     0,15,30,45 * * * * www-data lurker-prune
  If you are installing lurker in your home directory, add:
     0,15,30,45 * * * * lurker-prune
  
  This must be run with the ability to read and delete files from the
  web-server cache directory. If you don't configure this correctly,
  new email will not appear in your archive.
  
7 Configure your webserver.
  
  If you are using apache, and ran 'make install-config', then you should
  just need to put 'include /opt/local/etc/lurker/apache.conf' in your
  apache configuration. You will also need to enable mod_rewrite.
  
  To keep the hostname listed in cached HTML consistent, you might want to
  give your server a specific name and instruct it to always use this name
  for self-referencing URLs. In apache this is done with:
    ServerName www.mydomain.com
    UseCanonicalName on
  
  The following instructions apply to users of other web servers:
  
  You must make certain that .xsl and .xml files have type text/xml.
  You must set the default charset to UTF-8 for these files.
  You must make lurker your 404 error handler or another way of creating
      missing cache files (eg: apache's RewriteRule).
  You must pass the configured frontend to lurker.cgi in the QUERY_STRING.
      For example, invoking lurker as: 'lurker.cgi?/opt/local/var/www/lurker'
      will probably set this variable for you.
  
  Here are some samples of how to configure lurker with apache:
  (If you actually run apache, use the supplied config file instead!)

  These commands setup lurker to handle missing pages:
	AddType text/xml .xsl
	AddType text/xml .xml
	AddType message/rfc822 .rfc822
	AddDefaultCharset UTF-8
	
	# Optionally over-rule lurker's default config (needs mod_env)
	# SetEnv LURKER_CONFIG /path/to/lurker.conf
	# If you have multiple frontends, you need to specify which this is:
	# SetEnv LURKER_FRONTEND /opt/local/var/www
	ErrorDocument 404 /cgi-bin/lurker.cgi
   
   If you can use a Rewite Engine (avoids 404 log messages), this is best:

	AddType text/xml .xsl
	AddType text/xml .xml
	AddType message/rfc822 .rfc822
	AddDefaultCharset UTF-8

	# The E=LURKER_CONFIG is optional if you use the default config file
	# The E=LURKER_FRONTEND is optional if there is only one frontend
        RewriteEngine on
        RewriteCond %{REQUEST_FILENAME} !-s
        RewriteRule ^(attach|list|mbox|message|mindex|search|splash|thread|zap)/[^/]+$ /cgi-lurker/lurker.cgi [L,PT,E=LURKER_CONFIG:/path/to/lurker.conf,E=LURKER_FRONTEND:%{REQUEST_FILENAME}]

8 Point your browser at the url where lurker is installed

Enjoy!
