Manual installation

From refbase

(Difference between revisions)
Revision as of 17:12, 26 November 2005
WikiSysop (Talk | contribs)

← Previous diff
Current revision
WikiSysop (Talk | contribs)
separated install descriptions for shared hosts & deidicated servers
Line 1: Line 1:
-<h3>Manual installation of refbase</h3>+This document will guide you thru a manual installation of the refbase package. Before you proceed, please make sure that you have:
-<p>This document will guide you thru a manual installation of the refbase package. Before you proceed, please make sure that you have:</p>+* checked that your server meets the [[Requirements|requirements]]
 +* downloaded and unpacked the latest refbase [http://sourceforge.net/project/showfiles.php?group_id=64647 release package] or the refbase [[SVN_version|SVN version]]
 +* moved all files to your web directory
-<ul>+Please follow the steps that match your server setup (depending on whether you're installing refbase on a shared host or on a dedicated server):
- <li>a running web server (like the [http://httpd.apache.org/ Apache] HTTP Server)</li>+
- <li>a working installation of [http://www.php.net/ PHP] (version 4.1.0 or greater) and [http://www.mysql.com/ MySQL]</li>+
- <li>downloaded and unpacked [http://sourceforge.net/project/showfiles.php?group_id=64647&amp;package_id=61898 refbase]</li>+
- <li>moved all files to your web directory</li>+
-</ul>+
-<p>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 [http://www.mysql.com/doc/en/index.html MySQL online help].</p>+== 1 Installing refbase on a shared host ==
-<p><b>Important note</b>: refbase 0.8.0 [http://sourceforge.net/docman/display_doc.php?docid=19771&amp;group_id=64647 requires] the directives <code>magic_quotes_gpc</code>, <code>file_uploads</code> and <code>session.use_cookies</code> to be set to <b><code>ON</code></b> (or <b><code>1</code></b>, respectively) within your PHP configuration file <em>php.ini</em>. (Future versions of refbase will work regardless of the value of <code>magic_quotes_gpc</code>)</p>+'''Note''': We assume that your Internet Service Provider (ISP) has provided you with a tool such as [http://www.phpmyadmin.net/ phpMyAdmin] to manage your MySQL database(s) via a web interface.
-<p>In order to manually install the refbase package, we'll perform the following six steps:</p>+In order to manually install the refbase package on a hosted service, perform the following four steps:
-<h4>Step 1: Create a new MySQL database</h4>+=== 1.1 Create the refbase MySQL tables ===
-<p>Run the MySQL command line interpreter with root permissions and create a new database by executing the following code:</p>+Open your ISP's database management tool (such as phpMyAdmin or similar) and select one of your unused MySQL databases for refbase.
-<code>CREATE DATABASE <em>MYSQL_DATABASE_NAME</em>;</code>+'''Note''': If all of your MySQL databases are already in use, and you don't have permission to add any additional databases, you'll need to install the refbase tables within one of your existing MySQL databases. In that case you should [[Installing refbase#Installation over an existing database|rename the refbase tables]] before installation in order to avoid any table naming conflicts.
-<p>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:</p>+Now open the file ''install.sql'' in a text editor and copy its entire contents into the SQL command entry form provided by your ISP's database management tool. Press the form's submit button to install the refbase database tables in your selected MySQL database.
-<code>CREATE DATABASE <em>MYSQL_DATABASE_NAME</em> DEFAULT CHARACTER SET <em>CHAR_SET</em>;</code>+=== 1.2 Edit the file ''initialize/db.inc.php'' ===
-<p>In the above statements, replace <code><em>MYSQL_DATABASE_NAME</em></code> with a name that doesn't exist in your list of MySQL database names. In addition, replace <code><em>CHAR_SET</em></code> with the [http://dev.mysql.com/doc/mysql/en/charset.html character set] of your choice. As an example, if you've decided to name your new database <em>literature</em> and use the [http://dev.mysql.com/doc/mysql/en/charset-unicode.html Unicode] character set (UTF8 encoding) for your database, your <code>CREATE DATABASE</code> statement would read:</p>+Open the file ''initialize/db.inc.php'' in a text editor and edit the variables ''$username'' and ''$password'' to fit your needs. Your ISP has probably given you special values for ''$username'', ''$password'' and ''$databaseName'' which you must enter here. For ''$databaseName'', you should enter the database name that you've chosen in step 1.1. Please see the comments within the file for further guidance.
-<code>CREATE DATABASE literature DEFAULT CHARACTER SET utf8;</code>+=== 1.3 Setup your own admin user ===
-<p>This adds a new database <em>literature</em> to your MySQL database.</p>+Same as [[#2.5_Setup_your_own_admin_user|below]].
-<h4>Step 2: Edit the file <em>initialize/db.inc.php</em></h4>+=== 1.4 Customize the refbase interface ===
-<p>Open the file <em>initialize/db.inc.php</em> in a text editor and edit the variables <em>$username</em> and <em>$password</em> to fit your needs. For <em>$databaseName</em> enter the database name you've chosen in step 1. 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!)</p>+Same as [[#2.6_Customize_the_refbase_interface|below]].
 +== 2 Installing refbase on your own server ==
-<h4>Step 3: Add a new MySQL user and set his permissions</h4>+'''Note''': You'll need to have some very 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 [http://dev.mysql.com/doc/ MySQL online help].
-<p>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 root permissions and use the following <code>GRANT</code> statement:</p>+In order to manually install the refbase package on a server with full access to MySQL & the shell, perform the following six steps:
-<code>GRANT SELECT,INSERT,UPDATE,DELETE ON <em>MYSQL_DATABASE_NAME</em>.* TO <em>MYSQL_USER_NAME</em>@localhost IDENTIFIED BY '<em>MYSQL_PASSWORD</em>';</code>+=== 2.1 Create a new MySQL database ===
-<p>The <em>italic</em> items within the above statement must match the information you've provided in file <em>initialize/db.inc.php</em> (step 2). As an example, if you've entered the following in <em>initialize/db.inc.php</em>:</p>+Run the MySQL command line interpreter with admin permissions and create a new database by executing the following code:
-<pre> $hostName = "localhost";+ CREATE DATABASE ''MYSQL_DATABASE_NAME'';
- $databaseName = "literature";+
- $username = "litwww";+
- $password = "%l1t3ratur3?";</pre>+
-<p>your <code>GRANT</code> statement would read:</p>+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:
-<code>GRANT SELECT,INSERT,UPDATE,DELETE ON literature.* TO litwww@localhost IDENTIFIED BY '%l1t3ratur3?';</code>+ CREATE DATABASE ''MYSQL_DATABASE_NAME'' DEFAULT CHARACTER SET ''CHAR_SET'';
-<p>This adds a new user <em>litwww</em> to the <em>user</em> &amp; <em>db</em> tables of the <em>mysql</em> database and allows him to use only the SQL statements <code>SELECT</code>, <code>INSERT</code>, <code>UPDATE</code> and <code>DELETE</code> with any table of the <em>literature</em> database.</p>+In the above statements, replace <code>''MYSQL_DATABASE_NAME''</code> with a name that doesn't exist in your list of MySQL database names. In addition, replace <code>''CHAR_SET''</code> with the [http://dev.mysql.com/doc/mysql/en/charset.html character set] of your choice. As an example, if you've decided to name your new database ''literature'' and use the [http://dev.mysql.com/doc/mysql/en/charset-unicode.html Unicode] character set (UTF8 encoding) for your database, your <code>CREATE DATABASE</code> statement would read:
 + CREATE DATABASE literature DEFAULT CHARACTER SET utf8;
-<h4>Step 4: Load the MySQL database structure from file</h4>+This adds a new database ''literature'' to your list of MySQL databases.
-<p>The SQL dump file <em>install.sql</em> 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 root permissions and include the <code>--database</code> option:</p>+=== 2.2 Edit the file ''initialize/db.inc.php'' ===
-<code>mysql -h <em>HOST_NAME</em> -u <em>ADMIN_USER_NAME</em> -p --database=<em>MYSQL_DATABASE_NAME</em> &lt; <em>PATH_TO_SQL_DUMP_FILE</em></code>+Open the file ''initialize/db.inc.php'' 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 2.1. 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!
-<p>Again, you must adjust the <em>italic</em> items within the above statement to suit your setup. <code><em>HOST_NAME</em></code> should be the same as <em>$hostName</em> in <em>initialize/db.inc.php</em>. Similarly, <code><em>MYSQL_DATABASE_NAME</em></code> must match the value of the <em>$databaseName</em> variable in <em>initialize/db.inc.php</em>. For <code><em>ADMIN_USER_NAME</em></code> enter the name of the administrative user that has full access to the MySQL admin database. Finally, <code><em>PATH_TO_SQL_DUMP_FILE</em></code> must contain a valid path specification to the SQL dump file <em>install.sql</em>. Example: With the refbase web directory as current working directory, <em>root</em> being the admin user and using the values from the steps above, your import statement would read:</p>+=== 2.3 Add a new MySQL user and set his permissions ===
-<code>mysql -h localhost -u root -p --database=literature &lt; install.sql</code>+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 <code>GRANT</code> statement:
-<p>You'll be asked for the admin password. After the command has finished your installation of the refbase MySQL database is complete.</p>+ GRANT SELECT,INSERT,UPDATE,DELETE ON ''MYSQL_DATABASE_NAME''.* TO ''MYSQL_USER_NAME''@''HOST_NAME'' IDENTIFIED BY '<em>MYSQL_PASSWORD</em>';
 +The ''italic'' items within the above statement must match the information you've provided in file ''initialize/db.inc.php'' (step 2.2). As an example, if you've entered the following in ''initialize/db.inc.php'':
-<h4>Step 5: Setup your own admin user</h4>+ $hostName = "localhost";
 + $databaseName = "literature";
 + $username = "litwww";
 + $password = "%l1t3ratur3?";
-<p>Now, open a web browser and access the <em>index.php</em> script by typing:</p>+your <code>GRANT</code> statement would read:
-<code>http://SERVER_ADDRESS/PATH_ON_SERVER/index.php</code>+ GRANT SELECT,INSERT,UPDATE,DELETE ON literature.* TO litwww@localhost IDENTIFIED BY '%l1t3ratur3?';
-<p>In the above URL, replace the string <code>SERVER_ADDRESS</code> by your server name and <code>PATH_ON_SERVER</code> by the actual path specification to your web directory.</p>+This adds a new user ''litwww'' to the ''user'' &amp; ''db'' tables of the ''mysql'' database and allows him to use only the SQL statements <code>SELECT</code>, <code>INSERT</code>, <code>UPDATE</code> and <code>DELETE</code> with any table of the ''literature'' database.
-<p>This should bring up the main page of the refbase database. Login to the database by using:</p>+=== 2.4 Load the MySQL database structure from file ===
-<pre> email address = user@refbase.net+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 <code>--database</code> option:
- password = start</pre>+
-<p>You should see a welcome message at the top right corner of the page confirming your successful login:</p>+ mysql -h ''HOST_NAME'' -u ''ADMIN_USER_NAME'' -p --database=''MYSQL_DATABASE_NAME'' &lt; ''PATH_TO_SQL_DUMP_FILE''
-<center>[[Image:http://refbase.sourceforge.net/img/LoginConfirmation.jpg]]</center>+Again, you must adjust the ''italic'' items within the above statement to suit your setup. <code>''HOST_NAME''</code> should be the same as ''$hostName'' in ''initialize/db.inc.php''. Similarly, <code>''MYSQL_DATABASE_NAME''</code> must match the value of the ''$databaseName'' variable in ''initialize/db.inc.php''. For <code>''ADMIN_USER_NAME''</code> enter the name of the administrative user that has full access to the MySQL admin database. Finally, <code>''PATH_TO_SQL_DUMP_FILE''</code> 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:
-<p>Note that cookies must be enabled within your web browser, otherwise the login feature won't work properly.</p>+ mysql -h localhost -u root -p --database=literature &lt; install.sql
-<p>Click on <em>Add User</em> which should bring up an empty form. At a minimum, you have to specify the admin's first name &amp; last name, his institutional abbreviation as well as his email address and password. Then click the <em>Add User</em> button. You'll be shown a receipt page with the account details you just entered.</p>+You'll be asked for the admin password. After the command has finished your installation of the refbase MySQL database is complete.
-<p>Now open the file <em>initialize/ini.inc.php</em> in a text editor and change the value of the <em>$adminLoginEmail</em> variable to the email address you've specified for your new admin user.</p>+=== 2.5 Setup your own admin user ===
-<p>Log out from the database, then login again using the email address and password of your newly created admin account.</p>+Now, open a web browser and access the ''index.php'' script by typing:
-<p>You can now delete the initial user by choosing <em>Manage Users</em> 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)</p>+ http://SERVER_ADDRESS/PATH_ON_SERVER/index.php
 +In the above URL, replace the string <code>SERVER_ADDRESS</code> by your server name and <code>PATH_ON_SERVER</code> by the actual path specification to your web directory.
-<h4>Step 6: Customize the refbase interface</h4>+This should bring up the main page of the refbase database. Login to the database by using:
-<p>In order to properly configure your new database you'll need to edit the+ email address = user@refbase.net
-global configuration file: Open the file <em>initialize/ini.inc.php</em> &amp; edit all values of the contained variables to fit your needs. Please see the comments within the file for further guidance.</p>+ password = start
-<p>If you want to change the appearance of the web interface, checkout the CSS files <em>style.css</em> &amp; <em>style_print.css</em> and modify the contained CSS definitions to fit your taste.</p>+You should see a welcome message at the top right corner of the page confirming your successful login:
 + 
 +<center>http://refbase.sourceforge.net/img/LoginConfirmation.jpg</center>
 + 
 +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 &amp; 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/ini.inc.php'' 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 = ''user@refbase.net'' 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.
 + 
 +=== 2.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/ini.inc.php'' &amp; edit all values of the contained variables to fit your needs. Please see [[Configuring refbase]] and the comments within the file for further guidance.
 + 
 +If you want to change the appearance of the web interface, checkout the CSS and header/footer files and modify them to fit your taste. See also [[Integrating refbase into your web site]].
[[Category:Installation]] [[Category:Installation]]

Current revision

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

Please follow the steps that match your server setup (depending on whether you're installing refbase on a shared host or on a dedicated server):

Contents

1 Installing refbase on a shared host

Note: We assume that your Internet Service Provider (ISP) has provided you with a tool such as phpMyAdmin to manage your MySQL database(s) via a web interface.

In order to manually install the refbase package on a hosted service, perform the following four steps:

1.1 Create the refbase MySQL tables

Open your ISP's database management tool (such as phpMyAdmin or similar) and select one of your unused MySQL databases for refbase.

Note: If all of your MySQL databases are already in use, and you don't have permission to add any additional databases, you'll need to install the refbase tables within one of your existing MySQL databases. In that case you should rename the refbase tables before installation in order to avoid any table naming conflicts.

Now open the file install.sql in a text editor and copy its entire contents into the SQL command entry form provided by your ISP's database management tool. Press the form's submit button to install the refbase database tables in your selected MySQL database.

1.2 Edit the file initialize/db.inc.php

Open the file initialize/db.inc.php in a text editor and edit the variables $username and $password to fit your needs. Your ISP has probably given you special values for $username, $password and $databaseName which you must enter here. For $databaseName, you should enter the database name that you've chosen in step 1.1. Please see the comments within the file for further guidance.

1.3 Setup your own admin user

Same as below.

1.4 Customize the refbase interface

Same as below.

2 Installing refbase on your own server

Note: You'll need to have some very 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.

In order to manually install the refbase package on a server with full access to MySQL & the shell, perform the following six steps:

2.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:

CREATE DATABASE MYSQL_DATABASE_NAME;

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:

CREATE DATABASE MYSQL_DATABASE_NAME DEFAULT CHARACTER SET CHAR_SET;

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:

CREATE DATABASE literature DEFAULT CHARACTER SET utf8;

This adds a new database literature to your list of MySQL databases.

2.2 Edit the file initialize/db.inc.php

Open the file initialize/db.inc.php 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 2.1. 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!

2.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:

GRANT SELECT,INSERT,UPDATE,DELETE ON MYSQL_DATABASE_NAME.* TO MYSQL_USER_NAME@HOST_NAME IDENTIFIED BY 'MYSQL_PASSWORD';

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

$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.

2.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:

mysql -h HOST_NAME -u ADMIN_USER_NAME -p --database=MYSQL_DATABASE_NAME < PATH_TO_SQL_DUMP_FILE

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/db.inc.php. Similarly, MYSQL_DATABASE_NAME must match the value of the $databaseName variable in initialize/db.inc.php. 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.

2.5 Setup your own admin user

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

http://SERVER_ADDRESS/PATH_ON_SERVER/index.php

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  =  user@refbase.net
password       =  start

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

LoginConfirmation.jpg

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/ini.inc.php 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 = user@refbase.net 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.

2.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/ini.inc.php & edit all values of the contained variables to fit your needs. Please see Configuring refbase and the comments within the file for further guidance.

If you want to change the appearance of the web interface, checkout the CSS and header/footer files and modify them to fit your taste. See also Integrating refbase into your web site.