ABOUT KAPA

KAPA is a fork of SIPServer (git://git.evergreen-ils.org/SIPServer.git).
It provides a SIP interface for authenticating users against a variety
of backend systems.

In particular, KAPA can use SIP to authenticate against a list of valid
patron barcodes.  Clients regularly upload a list to the KAPA server;
KAPA imports the list into a local Postgres database, and then
authenticates against the database.

KAPA also provides the ability to connect to other backends.  For
example, it can use the FreeTDS library to authenticate against SQL
Server databases.

DEPENDENCIES

SIPServer is written entirely in Perl, but it require these CPAN
perl modules to run:

     Net::Server - The SIP server is a Net::Server::Prefork server
     XML::LibXML
	XML::LibXML depends on the C library libxml2
     XML::Parser
     XML::Simple - for parsing the config file
     UNIVERSAL::require - for loading the correct ILS interface module
     Clone - for running the test cases

SETUP

Let's assume that you want to authenticate users against a simple list
of valid barcodes provided by a library.  No PIN or other personal
information is required; the user just needs to have a barcode that is
in the library-supplied list.

1. Install the Perl dependencies listed above.

2. Install KAPA by putting the contents of this repo in /opt/SIPServer.

3. Install the Postgres database server.

4. Create a database named "barcodes":

    psql -c 'CREATE DATABASE barcodes;'

5. Initialize the new database (that is, create the necessary tables and
so on):

    psql -d barcodes -f postgres-db-init.sql

6. Create the /opt/flatfiles directory.  Flat files containing patron
barcodes will go here; each file should contain a simple list of patron
barcodes.  NB: You will need to establish your own process for uploading
files to this location (e.g. a web-based upload form).

7. Create the /opt/flatfiles-daily directory.  This contains backups of
flat files that have been processed by KAPA.

8. Rename process-libraryfiles.py.example to process-libraryfiles.py,
then edit the file:

    (a) Around line 49, edit the arguments for the psycopg2.connect
        function to use the correct hostname, username, and password for
        your local Postgres database.

    (b) (optional) If you want to validate the barcodes in your flat
        file based on barcode patterns (e.g. prefixes), around line 29,
        add a regular expression to the libraryPatterns array.

9. Create cron jobs to periodically run the following commands:

    python /opt/SIPServer/process-libraryfiles.py
    bash /opt/SIPServer/process-libraryfiles-cleanup.sh

The first command grabs the contents of any files that have been
uploaded to /opt/flatfiles, deletes any existing barcodes for that
library from the database, and imports the new ones.  The second command
rotates uploaded flat files out of the /opt/flatfiles directory.

10. Rename SIPconfig.xml.example to SIPconfig.xml, then modify it to make
KAPA aware of the database:

    (a) In the <accounts> block, define login information to be used by
        SIP clients.  The "institution" attribute corresponds to entries
        in the <institutions> block.

    (b) In the <institutions> block, add an entry for your institution.
        Use SITE1 as an example.  This is the piece that tells KAPA how
        to connect to your local Postgres database.

11. Start KAPA:

    cd /opt/SIPServer
    perl SIPServer.pm SIPconfig.xml > /dev/null 2>&1 & 
    echo $! > /var/run/sip2-server.pid

SIPServer is prone to memory leaks, so you may want to schedule a nightly
restart of KAPA.

LOGGING

SIPServer uses syslog() for status and debugging messages.  All
syslog messages are logged using the syslog facility 'local6'.
If you need to change this, because something else on your system
is already using that facililty, just change the definition of
'LOG_SIP' at the top of the file SIPServer.pm

Make sure to update your syslog configuration to capture facility
'local6' and record it.

CONTRIBUTORS

SIPServer was initially developed by David J. Fiander and others (see
git version history for full details).

KAPA components were developed by Kevin Reed and are currently
maintained by the BC Libraries Cooperative (http://bc.libraries.coop).