ASPSeek installation, run-time configuration and troubleshooting.


Quick install
=============
For the impatient, here's what you need to do (please read Step-by-step install
below for more information):

a. Install the appropriate RDBMS if you haven't done so.
b. Run ./configure && make && make install.
c. Create new user and database in RDBMS.
d. Create SQL tables from etc/sql/ (take appropriate one).
e. Read and edit configuration files in etc installation directory.
f. Run sbin/index, then sbin/searchd -D.
g. Put s.cgi in your Web server's cgi-bin.
h. Put images from etc/img to /img dir under your web server document root
i. Run sbin/index on a regular basis to update database.
k. Open http://localhost/cgi-bin/s.cgi and do the search!


Upgrade
=======

If you are upgraging from 1.0.x to 1.2, please note that default database
format is incompatible with one of 1.0.x versions, because of new (better)
storage modes and UNICODE support. So, while upgrading you basically have
two options:

1. (preferred) Delete SQL database content and even SQL tables itsetf, recreate
it from etc/your_dbms/tables.sql, delete aspseek/var contents and reindex
everything all over again.

2. Use options --disable-fast-clones --disable-unicode to configure, and set
"CompactStorage no" and "IncrementalCitations no" in both aspseek.conf and
searchd.conf.

Please DON'T FORGET to upgrade s.cgi in your webserver cgi-bin directory, as
old s.cgi will not understand new searchd and can just stay in infinite idle
loop or produce incorrect results.


Step-by-step install
====================


1. System requirements
----------------------

We use ASPLinux distribution (http://www.asp-linux.com), which is RedHat
compatible, to develop and run ASPSeek, but is should run on (or be easy to
port to - due to autoconf) other UNIX variants. At the moment the following
platforms are supported:

	Linux 2.x
	FreeBSD 4.x

Please report your success with other platforms to aseek@sw.com.sg.

You also need RDBMS. MySQL 3.23 or later, or Oracle 8.1.5 or later are
supported in this version. Support for more databases is planned for
future releases.

To build binaries, you need decent C++ compiler (we use GNU g++), STL library
(we use one from libg++) and GNU make utility (non-GNU make can fail to work).

NOTE for RedHat users: egcs from RedHat 6.0 and 6.1 are _broken_ and can't
compile ASPSeek sources correctly. Either upgrade egcs and libstdc++ to ones
from RedHat 6.2, or compile without -O2 (type export CXXFLAGS="-O0" before
./configure).


2. Getting the sources
----------------------

You can always get the latest release of ASPSeek from product's home page,
http://www.sw.com.sg/products/aspseek/

Then you should untar it by running

gzip -dc aspseek-x.y.z.tar.gz | tar xf -

or, if you have GNU tar, 

tar xzf aspseek-x.y.z.tar.gz


If you are curious and want to stay at the bleeding edge, we have opened
anonymous read-only access to CVS, there you can get the latest sources.

We have also opened CVS access via Web:
http://www.asplinux.ru/cgi-bin/cvsweb.cgi/aspseek/

To get the sources from CVS, you should use the following commands:
export CVSROOT=:pserver:anoncvs@www.asplinux.ru:/home/cvs
cvs login [Here you should type the password: anoncvs]
cvs -z9 co aspseek
cvs logout

For next time, issue "cvs -z9 update aspseek" instead of "cvs -z9 co aspseek".

After downloading, please run script ./cvsprep.

PLEASE NOTE that if you use version from CVS, it may be unstable and maybe
will not compile at all. So you should know what you are doing.

3. Configuration
----------------

cd aspseek-x.y.z
./configure --your-options

For example, to specify your non-standard MySQL location, add
--with-mysql=/path/to/mysql. To specify ASPSeek installation directory
(instead of standard /usr/local/aspseek), add --prefix=/some/dir.

If you need https:// support, please use --with-ssl flag. This will need
OpenSSL (available from http://www.openssl.org) installed to /usr/local/ssl.
If you have OpenSSL in another dir (say, /usr/ssl), use --with-ssl=/usr/ssl.

Run ./configure --help to see all available configure options.


4. Compilation and installation
-------------------------------

Just run make && make install. If anything goes wrong, try to use GNU make
instead. It is often installed as gmake.


5. Run-time configuration
-------------------------

First, you should create RDMBS user and database. See your RDBMS manual for
details.

Then,
cd /usr/local/aspseek (or directory you have just installed ASPSeek to)
cd etc

Two main configuration files are aspseek.conf and searchd.conf. You should
edit these files manually and provide all necessary information such as
RDBMS name, user and password, what sites do you want to index and how often
etc. There are a lot of comments in that files so just read-and-modify.

If you want ASPSeek to search documents which contains information not only
in English, look at charsets.conf and stopwords.conf, there you should 
uncomment all needed charsets and stopword files,

There's also template file s.htm, which is used by search front-end s.cgi.
It tells how search forms and results should be displayed. For the first
time default template will work for you, and if you'll want to modify it,
read doc/templates.txt for in-depth explanation.


6. First indexing
-----------------

Just run sbin/index. It will crawl the sites you provided in aspseek.conf
and put resulting data in MySQL tables and in var directory of ASPSeek
installation.

If you are indexing more than one server, flags -N and -R should be very
useful.

-N <num> sets the number of indexing threads (default is 1), and
-R <num> sets the number of resolvers (default is NUM_THREADS/5 + 1)

Setting number of indexing threads to more than a number of servers indexed
makes no sense, because index gets one document at a time from one server.

For other index flags, run index -h


7. First searching
------------------

First, you should run sbin/searchd -D. This is search daemon, which provides
interface to database, caches results and so on.

Copy image files from etc/img installation directory to /img directory
under your web server document root.

Copy bin/s.cgi to your Web server cgi-bin directory and point your browser
to it. You should see the search form.

We will be happy to see a report about successful installation from you, so
please send one to <aseek@sw.com.sg>.


8. Further reading
------------------

Please read various files in doc/ and man/ subdirectories. All configuration
files are heavily documented too.

If you haven't read FEATURES yet, now it's time to take a look there, so you
will get an idea of what ASPSeek can do for you.

If you have some problems or questions, please read our FAQ, if that
doesn't help, ask developers <aseek@sw.com.sg>.

You can also subscribe to ASPSeek users mailing list to ask questions,
share ideas, and communicate in general with other users and developers.
To subscribe, please send mail to majordomo@lists.asplinux.ru with the line
"subscribe aseek-users" in message body. List archives are available from
http://www.mail-archive.com/aseek-users%40lists.asplinux.ru/
