analysis/idp_server/README.IDP.txt

   1 This directory contains the necessary scripts and machinery for running
   2 the IDP graph calculation service. Installation is a little intricate as
   3 it includes several components:
   4
   5 * The IDP system itself (available from
   6   http://dtai.cs.kuleuven.be/krr/software/idp)
   7 * The *.idp and *.lua scripts in this directory
   8 * A Perl DBI-compatible database for the storage of calculation results
   9 * A Gearman server for dispatching calculation requests
  10 * The Perl script in this directory, which functions as a Gearman worker
  11 * The CGI script in this directory, which functions as a Gearman client
  12
  13 INSTALLATION
  14 ============
  15
  16 0. Decide on a location for the following:
  17 * The IDP system software (e.g. /usr/local/idp)
  18 * The graph calculation IDP scripts (e.g. $HOME/graphcalc or
  19   /usr/local/idp/script)
  20 * The database for storage of calculation results
  21
  22 Support software and packages
  23 -----------------------------
  24 1. Compile and install IDP for your platform into your chosen directory.
  25 See http://dtai.cs.kuleuven.be/krr/software/idp for more information.
  26
  27 2. Install (or designate) a Gearman server. The relevant Ubuntu package is 'gearman-job-server'; installing it will set up a server on localhost.
  28
  29 3. Ensure that the following Perl (v5.12 or later) dependencies are
  30 installed:
  31 * Gearman::Client
  32 * Gearman::Worker
  33 * Graph
  34 * Graph::Reader::Dot
  35 * IPC::Run
  36 * JSON
  37 * Text::Tradition::Analysis
  38 * Text::Tradition::Directory
  39 * TryCatch
  40
  41 4. Install (or designate) a Supervisor daemon. The relevant Ubuntu
  42 package is 'supervisor'; installing it will start a daemon on localhost.
  43
  44 Graph calculation service components
  45 ------------------------------------
  46
  47 5. Create a file /etc/graphcalc.conf as in the example here, substituting appropriate
  48 values for your system:
  49 --- START CONF FILE ---
  50 DBTYPE = <database server type (e.g. mysql / Pg / SQLite / Sybase),
  51                 default mysql>
  52 DBHOST = <database server host name or IP, default 127.0.0.1>
  53 DBPORT = <database server port, default 3006>
  54 DBNAME = <database for storage of results, default 'idpresult'>
  55 DBUSER = <database username, default undef>
  56 DBPASS = <password for database username, default undef>
  57 GEARMAN_SERVER = <Gearman server host and port,
  58                 default 127.0.0.1:4730>
  59 IDPBINPATH = <location of 'idp' binary, default /usr/local/idp/bin>
  60 IDPSCRIPTPATH = <location of graph calculation scripts,
  61                 default /usr/local/idp/script>
  62 TMPDIR = <location for temporary files, default /var/tmp>
  63 ---- END CONF FILE ----
  64
  65 The DBTYPE should be set to a value for which a Perl DBD::* module
  66 exists. You may optionally specify a value for 'DSN' instead of listing
  67 the type, host, port, and name separately, but this will break the
  68 backup and restore scripts.
  69
  70 6. Copy the *.idp, *.lua, and *.pl scripts from this directory to the
  71 directory specified in IDPSCRIPTPATH.
  72
  73 7. Create a database for the storage of calculation results. On MySQL
  74 this can be done with the following sequence of statements, where
  75 'user', 'host', and 'password' are chosen appropriately:
  76
  77 CREATE DATABASE idpresult;
  78 GRANT ALL PRIVILEGES ON idpresult.* TO "[user]"@"[host]"
  79 --> IDENTIFIED BY "[password]";
  80 FLUSH PRIVILEGES;
  81
  82 8. Copy the graphcalc.cgi script to the cgi-bin directory of your
  83 webserver, ensuring that it is executable and that the file permissions
  84 are set appropriately.
  85
  86 9. Start one or more instances of the gearman_worker.pl script. It is
  87 recommended that this be done through the Supervisor daemon. An example
  88 Supervisor configuration script is given here:
  89
  90 --- START SUPERVISOR CONF ---
  91 [program:graphcalc_worker]
  92 command=/usr/local/idp/script/graphcalc_worker.pl
  93 process_name=%(program_name)s.%(process_num)s
  94 numprocs=4
  95 user=www-data
  96 ---- END SUPERVISOR CONF ----
  97
  98 10. Run the idpinit.pl script to initialize the database.
  99
 100 11. Requests can now be sent via CGI to graphcalc - you're done!
 101
 102 Maintenance scripts
 103 -------------------
 104 Two maintenance scripts, idpbackup.pl and idprestore.pl, are included
 105 with this distribution.  Each of these scripts can be invoked with no
 106 arguments.
 107
 108 At the moment the restore script assumes that the database is on a MySQL
 109 server; it does not know how to drop tables for any other database. The
 110 backup script will dump all calculation results to
 111 TMPDIR/idpresults.json; the restore script will wipe the database and
 112 load them from the temp file. If nothing unexpected happens, the restore
 113 script will also clean up the temp file.