Manual installation

From refbase

Revision as of 11:28, 29 March 2007; view current revision
←Older revision | Newer revision→

This document will guide you thru a manual installation of the refbase package. Before you proceed, please make sure that you have:

  • a running web server (like the Apache HTTP Server)
  • a working installation of PHP (version 4.1.0 or greater) and MySQL
    • the Apachefriends-Project offers a complete solution for above mentioned services (Apache, PHP, MySQL), called XAMPP. The easy-to-use-package runs under different environments (Linux, Windows, MacOS)
  • downloaded and unpacked refbase
  • moved all files to your web directory

Additionally, you'll need to have some basic knowledge of MySQL, e.g., we assume that you know how to run the MySQL command line interpreter and how to execute MySQL commands. If you require help with this, please refer to the MySQL online help. If you're trying to install refbase on a shared host, your Internet Service Provider (ISP) may provide you with a tool such as phpMyAdmin to manage your MySQL database(s).

Important note: refbase-0.9.0 requires the directives file_uploads and session.use_cookies to be set to ON (or 1, respectively) within your PHP configuration file php.ini.

In order to manually install the refbase package, we'll perform the following six steps:


Step 1: Create a new MySQL database

Run the MySQL command line interpreter with admin permissions and create a new database by executing the following code:


If you've got MySQL 4.1.x (or greater) installed and you want to use another character set than the default one ('latin1', i.e. 'ISO-8859-1 West European') then use:


In the above statements, replace MYSQL_DATABASE_NAME with a name that doesn't exist in your list of MySQL database names. In addition, replace CHAR_SET with the character set of your choice. As an example, if you've decided to name your new database literature and use the Unicode character set (UTF8 encoding) for your database, your CREATE DATABASE statement would read:


This adds a new database literature to your list of MySQL databases. Note that if you're installing refbase on a shared host, you may not have permission to add any additional databases. In that case you may want to skip this step and, instead, rename the refbase tables before installation in order to avoid any table naming conflicts.

Step 2: Edit the file initialize/

Open the file initialize/ in a text editor and edit the variables $username and $password to fit your needs. For $databaseName enter the database name you've chosen in step 1. Note that if you're on a hosted service, special values for $username, $password and $databaseName were probably assigned to you by your ISP. Please see the comments within the file for further guidance. (Note that you may be able to use the refbase package without modifying these variables, but we highly recommend not to use the default values!)

Step 3: Add a new MySQL user and set his permissions

To avoid any security risks we'll add a new MySQL user to the MySQL database. This user is granted only those permissions that are required to access the literature database. To add this MySQL user, run the MySQL command line interpreter with admin permissions and use the following GRANT statement:


The italic items within the above statement must match the information you've provided in file initialize/ (step 2). As an example, if you've entered the following in initialize/

$hostName = "localhost";
$databaseName = "literature";
$username = "litwww";
$password = "%l1t3ratur3?";

your GRANT statement would read:

GRANT SELECT,INSERT,UPDATE,DELETE ON literature.* TO litwww@localhost IDENTIFIED BY '%l1t3ratur3?';

This adds a new user litwww to the user & db tables of the mysql database and allows him to use only the SQL statements SELECT, INSERT, UPDATE and DELETE with any table of the literature database. Please note that this step may not be possible (or in fact necessary) if you're installing refbase on a shared host which, by default, grants you only limited MySQL user privileges.

Step 4: Load the MySQL database structure from file

The SQL dump file install.sql that comes with the refbase package contains everything you'll need to setup the refbase database tables. In addition it will provide some sample data. To import this file into your newly created MySQL database, run the MySQL command line interpreter with admin permissions and include the --database option:


Again, you must adjust the italic items within the above statement to suit your setup. HOST_NAME should be the same as $hostName in initialize/ Similarly, MYSQL_DATABASE_NAME must match the value of the $databaseName variable in initialize/ For ADMIN_USER_NAME enter the name of the administrative user that has full access to the MySQL admin database. Finally, PATH_TO_SQL_DUMP_FILE must contain a valid path specification to the SQL dump file install.sql. Example: With the refbase web directory as current working directory, root being the admin user and using the values from the steps above, your import statement would read:

mysql -h localhost -u root -p --database=literature < install.sql

You'll be asked for the admin password. After the command has finished your installation of the refbase MySQL database is complete. Note that if you're on a hosted service, you'll probably have no permission to perform the above command. However, as an alternative, you can copy the entire contents of install.sql into the SQL command entry form provided by MySQL web administration tools such as phpMyAdmin. This will allow you to install the refbase database tables without the need to execute above command.

Step 5: Setup your own admin user

Now, open a web browser and access the index.php script by typing:


In the above URL, replace the string SERVER_ADDRESS by your server name and PATH_ON_SERVER by the actual path specification to your web directory.

This should bring up the main page of the refbase database. Login to the database by using:

email address  =
password       =  start

You should see a welcome message at the top right corner of the page confirming your successful login:


Note that cookies must be enabled within your web browser, otherwise the login feature won't work properly.

Click on Add User which should bring up an empty form. At a minimum, you have to specify the admin's first name & last name, his institutional abbreviation as well as his email address and password. Then click the Add User button. You'll be shown a receipt page with the account details you just entered.

Now open the file initialize/ in a text editor and change the value of the $adminLoginEmail variable to the email address you've specified for your new admin user.

Log out from the database, then login again using the email address and password of your newly created admin account.

You can now delete the initial user by choosing Manage Users and clicking the appropriate trash icon. (However, we recommend to keep this user until you've explored the example records that come with the database)

Especially note that you won't be able to login using email address = and password = start if you've already changed the value of the $adminLoginEmail variable *before* attempting to login for the first time. This variable must only be changed *after* you've created your own admin user.

Step 6: Customize the refbase interface

In order to properly configure your new database you'll need to edit the global configuration file: Open the file initialize/ & edit all values of the contained variables to fit your needs. Please see the comments within the file for further guidance.

If you want to change the appearance of the web interface, checkout the CSS files style.css & style_print.css and modify the contained CSS definitions to fit your taste.