Installing PublicationsList.org on your own server

It is possible to obtain a site license for installing a local copy of the PublicationsList.org software on an internal university server, providing convenient publications list management services for all your academic staff. Please contact us to discuss your requirements.

This guide describes how to install PublicationsList on your own server. PublicationsList is a PHP web application, which uses some open source tools for bibliography format conversions; Java and Lucene for full text indexing and XPDF for generating thumbnails of papers.

It is possible to configure automated harvesting from a local installation of publications list; see the DSpace harvesting module for details and contact us if you use a different repository system.

The software has been tested on Linux systems running Apache and PHP (version 5).

0. Where to install publicationslist.org

You can install the publicationslist software in any web accessible folder, e.g.

e.g. if you install in: http://yoursite.edu/publist/ The welcome and registration page will be on: http://yoursite.edu/publist/index.html Public URLs for individual publications lists will look like: http://yoursite.edu/publist/a.einstein

Before you install publicationslist.org, you'll need:

• Apache2, PHP5, make, + a text editor
• Enable the apache module: mod_rewrite
• Enable .htaccess support in your web folder: ('AllowOverride All' in httpd.conf)
• Optional: Sun Java 6 (if you need full text search supported)
• Optional: XPDF and netpbm (needed to generate thumbnails of uploaded PDFs)

1. Download and unpacking the code

You can download the code from publist-1.1.tgz (updated Nov 30 2009) [password required - contact us for details], and unpack it in a web visible directory, e.g.:

# e.g. make a directory for the installation mkdir /var/www/publist cd /var/www/publist # copy the tgz here and extract to current directory: tar xvfz publist-1.0.tgz # make the directories for storing user data. make install

The software extracts to the current directory, with an outline of the directory structure below:

index.html --- the welcome page .htaccess --- enable short URLs to publications lists [section 4 below] php/ --- the code. .htaccess --- *** need to enable mod_auth here [section 3] signin.php --- initial registration page publist.php --- the page for editing a list config.tmp --- *important* configuration settings for your install (see below) import/ --- binaries from bibutils for metadata conversions private/ --- private data storage *writable by apache user* .htaccess --- hide data from apache {userid}/ --- settings for {userid} data/ --- public web visible area *writable by apache user* {userid}/index.html --- publications list for {userid} {userid}/publist.js --- JSON version of metadata {userid}/atom.xml --- ATOM feed version ... + additional images, CSS and javascript files.

Data on publications is stored in JSON and XML formats in the file system in the private/ and data/ subdirectories. The private/ folder is protected by a .htaccess file (set in 'make install' step above); you can check that this is set up correctly on your system by pointing your web browser at 'http://yoursite.edu/publist/private/' to make sure that you get a 'Forbidden' response. If you get a folder listing instead, check that you have enabled .htaccess support for the folder in your Apache configuration.

2. Edit the configuration files

A sample configuration file is provided in php/config-sample.txt which you need to copy to php/config.tmp and edit to point to your installation URL:

cd publist/php/ cp config-sample.txt config.tmp vi config.tmp # ... or your preferred editor

You need to edit the settings below to point at the URL of your installation, and configure custom messages; sample settings are shown below, and there is more documentation in the comments area of the 'config-sample.txt' file e.g. :

$basepath = "http://yoursite.edu/publist/"; $publishPath = "/publist/"; $localInstall = 1; $enableModAuth = 1; $authSite = "bu.edu"; $authDebug=1; $publistBrand = "Publications Lists @ BU"; $publistPoweredBy = "PublicationsList.org @ BU"; // To enable the automated repository harvester: $enableCollections = true; $trackbackCode = "xxx999";

3. Integration with university authentication systems using mod_auth

If you have set up Apache's mod_auth module for integration of logins with a university system, you should enable it for the php/ directory (e.g. using .htaccess or a httpd.conf setting) and also edit the relevant lines of php/config.tmp:

$enableModAuth = 1; $authSite = "bu.edu";

For testing *only* you can also add the line:

$authDebug = 1; // This allows you to test logging in as a particular {REMOTE_USER} using: // http://yoursite.edu/publist/php/signin.php?ru=john.doe

4. Details of Apache .htaccess configuration

PublicationsList generates short URLs for publications lists, as they are more memorable, e.g. "http://publicationslist.org/fred". The actual html file lives in a longer URL - "http://publicationslist.org/data/fred/index.html". To use this feature, you need to enable '.htaccess' in your apache configuration, and ensure that the 'mod_rewrite' module is installed. For example, on Ubuntu the relevant setting is in /etc/apache2/sites-enabled/000-default , which needs to be changed from 'AllowOverride None' to 'AllowOverride All' for your publications list installation. On other linux variants the apache configuration settings might be stored in "httpd.conf" instead.

<Directory /var/www/> Options Indexes FollowSymLinks MultiViews AllowOverride All Order allow,deny allow from all </Directory>

... then restart Apache after making any changes to its configuration:

# Enable the mod_rewrite apache module # On ubuntu you can use: cd /etc/apache2/mods-enabled sudo ln -s ../mods-available/rewrite.load rewrite.load # restart the web server (on Ubuntu) sudo /etc/init.d/apache2 restart

To switch on the rewriting, you can copy the sample top level htaccess file in 'htaccess-sample.txt' to '.htaccess'. This does a pattern match on the URLs, so you may need to edit the file to match the install path:

cd /var/www/publist/ ### e.g. if you've installed at http://yoursite.edu/ :- cp htaccess-sample.txt .htaccess ### -OR- if you've installed at http://yoursite.edu/publist/ cp htaccess-sample2.txt .htaccess # if you've installed to another path, edit the sample2 version.

NB - any mistakes in an .htaccess file can cause apache to fail to render web pages - so it is best to experiment on a development server first.

5. Bibutils configuration

PublicationsList uses the bibutils conversion tools for converting between different bibliography formats (bibtex, endnote, MODS etc). Static-linked binary versions of these are included in the import/ directory of your installation. If these do not work on your system (there can sometimes be problems with Linux binaries on different machines - you can try running './import/bib2xml -?' from the command line to check), you can download the source code from the bibutils website and install your own copy. The paths are configured in the 'php/importConfig.tmp' configuration file if you need to point at a different version of bibutils.

6. Testing your installation

To check that your installation is working, point your browser at http://yoursite.edu/publist/ and click the 'sign in' link on the right. This should take you to a page where you can enter your name to create your publications list - after this, usage should be the same as the standard version on publicationslist.org.

If you have the $authDebug = 1; setting in php/config.tmp, you can also try logging in as a particular user id (e.g. 'user123') by visiting: http://yoursite.edu/publist/php/signin.php?ru=user123 This bypasses the mod_auth authentication, so this setting must be switched off for production use.