Installing refbase

This document describes how to install refbase.

Web-based installation

This section describes how to install refbase using the install script (install.php) that comes with the refbase package. Alternative installation methods are described below. See the 'INSTALL' file that comes with the refbase package for latest information regarding the installation process.

Check requirements

Please make sure that your server meets the requirements.

Download and install scripts

Download the latest stable release version (or, alternatively, get the latest development version of refbase from the refbase SVN repository). Then, unpack the download archive (if necessary) and copy all refbase scripts to your server's web directory.

Additionally, you may want to download Bibutils and copy the binaries to an executable path. Bibutils provides additional import and export funtionality to refbase (e.g. support for Endnote & BibTeX). It is optional, but highly recommended.

Configure database settings

Please be sure to configure important database settings prior to installation. While you might be able to use the refbase package without modifying the default settings, we highly recommend not to use the default values.

Install refbase via install.php

Point your web browser to install.php, and fill out and submit the install form(*) to complete the installation process.

(*) In case you're curious, the install form looks like this.

Note that the install script currently requires a user with full access to the mysql database (more info below). I.e., if you're trying to install refbase on a shared host with limited MySQL access privileges, you may need to perform a manual installation instead.

Alternative installation methods

Manual installation

If you're experiencing problems with the web-based installation you can try a manual installation instead.

Gentoo Linux

Gentoo has an ebuild of refbase in portage, so you can merely:

$ emerge refbase

Mandrake/Mandriva Linux

refbase RPMs are available. RPMs for refbase-0.9.5 are available e.g. here and here. To install the refbase RPM, use urpmi or rpmdrake:

$ urpmi refbase

then finish the installation by pointing your web browser to http://localhost/refbase/install.php

Virtual machine

You may use the gratis VMware Player with a refbase virtual appliance (hosted by NUCAPT).

WOS Portable

Windows users can download the free and open source WOS Portable to have an Apache/MySQL/PHP stack (which can even be run from a USB stick). The refbase package can reportedly be downloaded from their premium site. Non-members can download the refbase WOS package from NUCAPT.

Installation Troubleshooting

A list of possible problems and their solutions can be found in the Installation-Troubleshooting section.

Installation over an existing database

In the install form, you will find a cautionary note:

Note that, if there's already an existing database with the name specified
in $databaseName, clicking the Install button will overwrite ALL data in that
database!

Actually, this note is only true if you're installing into an existing refbase database. The refbase install.php script will NOT delete an existing database but will only overwrite those tables in the specifed database that have names identical to the ones used by refbase. refbase table names are specified in files initialize/db.inc.php & install.sql (or update.sql) and can be changed there to avoid any name conflicts with existing tables.

In other words, if the table names in your existing database don't conflict with the table names used by refbase (or if you rename the refbase table names in db.inc.php AND in install.sql prior to installation so that they don't conflict with existing table names), then you should be able to use install.php for installation of refbase into any existing database.

However, it is a very good idea to make a full backup of your existing database prior to installation. Also, it may be worth to first do some testing with a non-critical database copy.

Additional web-install requirements

In order to run the install.php script as described above, you will need a MySQL username with permission to modify the database named mysql which stores the MySQL user privilege information. This is since the refbase install script adds a dedicated MySQL user to the mysql database which will be used with your refbase application (more info).

Some shared hosts do not provide MySQL usernames with the required permissions, but instead provide alternate interfaces for MySQL username administration such as a web-based control center. If you face this restriction, you will need to perform a manual installation.