MRBS Installation Instructions
REQUIREMENTS
---------------------------------------------------------------------------
MRBS works with both MySQL (Version 4 and above) and PostgreSQL (Version 7
and above) systems. You must have PHP with support for your chosen database
system installed and working for this application. See the PHP (www.php.net),
MySQL (www.mysql.com), and PostgreSQL (www.postgresql.org) sites for more
info on setting these up. You need to know how to install, secure, run,
maintain, and back up your chosen database system.
No optional PHP packages (other than the database system) are required for
this application. PHP Version 4 or later is required.
You can run PHP either as a CGI or with a direct module interface (also called
SAPI). These servers include Apache, Microsoft Internet Information Server,
Netscape and iPlanet servers. Many other servers have support for ISAPI, the
Microsoft module interface.
You'll get better performance with PHP setup as a module. Not only will you
not have to deal with the CGI performance hit, but you'll be able to use PHP's
database connection pooling. However, be careful that you don't exceed
the maximum number of connections allowed to your database; with connection
pooling PHP/Apache can potentially create a connection from each Apache
child server to the database.
Also many MRBS authentication schemes use basic HTTP authentication. These
don't work if you run PHP as a CGI.
If you are using PHP as an Apache module, you probably want to ensure that
the Apache MaxRequestsPerChild is not set to 0, in case of undetected memory
leaks in PHP or MRBS.
FILE UNPACKING
---------------------------------------------------------------------------
To install MRBS, just unpack the distribution into a temporary directory,
then copy the files in the "web" subdirectory into a new directory somewhere
your web server can find them.
For example:
Unpack the software into a new temporary directory, something like this:
$ tar -xvzf ~/download/mrbs-1.0.tgz (or whatever version)
$ cd mrbs-1.0 (or whatever version)
If you are upgrading from a previous version of MRBS, you should save your
"config.inc.php" file so you can compare and update the new file with your
site-specific changes. Then rename your existing MRBS web server directory.
For example:
$ cp /var/lib/apache/htdocs/mrbs/config.inc.php config.site.inc
$ mv /var/lib/apache/htdocs/mrbs /var/lib/apache/htdocs/mrbs.old
Now install MRBS by copying the contents of the "web" subdirectory of the
distribution somewhere your web server can find it. For example:
$ cp -r web /var/lib/apache/htdocs/mrbs
DATABASE SETUP
---------------------------------------------------------------------------
For a new install:
You can place the MRBS database tables in an existing database or
create a new database with the following:
[MySQL] $ mysqladmin create mrbs
[PostgreSQL] $ createdb mrbs
(This will create a database named "mrbs", but you can use any name.)
Create the MRBS tables using the supplied tables.*.sql file:
[MySQL] $ mysql mrbs < tables.my.sql
[PostgreSQL] $ psql -a -f tables.pg.sql mrbs
where "mrbs" is the name of your database (mentioned above).
This will create all the needed tables.
You may need to set rights on the tables; for PostgreSQL see "grant.pg.sql".
If you use a PHP version less than 4.2, you will also need to replace the pgsql
driver file pgsql.inc with pgsql.before_php42.inc, and rename it to pgsql.inc.
If you need to delete the tables, for PostgreSQL see "destroy.pg.sql".
The tables are now empty and ready for use. If you want to add a few sample
areas and rooms without going through the Admin function, use this script:
[MySQL] $ mysql mrbs < sample-data.sql
[PostgreSQL] $ psql -a -f sample-data.sql mrbs
Substitute the database name you used for "mrbs".
This script is only for use in a newly initialized database! (It will not
work properly in a database where the ID counters are greater than 0.)
Also see the description of testdata.php in the README file.
For an upgrade:
If you are upgrading from MRBS 1.2-pre3 or later, your database will be
upgraded automatically if necessary when you first run MRBS. You will
be prompted for a database (not MRBS) username and password with rights
to create and alter tables. Otherwise, please se the UPGRADE file.
For a second installation or to use different table names:
If you have table name conflicts or want to do a second installation
and only have access to one database, then you can modify the 'mrbs_'
prefix for the table names.
In tables.*.sql you will need to change the table names and then follow
the instructions above for creating the tables in your database.
When editing config.inc.php, you need to change the table name prefix
from "mrbs_" to the value you chose using the variable $db_tbl_prefix.
WARNING: All of the .sql files are setup to use the 'mrbs_' prefix
therefore you will have to edit them before you use them if you
change the prefix for your tables.
Maintenance:
Be sure to back up your database regularly.
For PostgreSQL, be sure to run the "vacuum" command regularly.
You can clean out old entries from your database using the supplied SQL
scripts purge.my.sql (for MySQL) and purge.pg.sql (for PostgreSQL). Read
the comments at the top of the scripts before using them.
ADDING EXTRA COLUMNS TO THE DATABASE TABLES
---------------------------------------------------------------------------
It is possible to add extra columns to the room and users tables, if you need
to hold extra information about rooms and users. For example you might want
to add a column in the room table to record whether or not a room has a coffee
machine and you might want to record the phone numbers of users. (Note that
the users table is only used if you are using the 'db' authentication scheme).
To add extra columns, just go into your database administration tool, eg
phpMyAdmin, and add the extra columns manually. MRBS will then recognise them
and handle them automatically, displaying the information in the lists of rooms
and users and allowing you to edit the data in the appropriate forms.
At the moment only text, varchar, int, smallint and tinyint columns are
supported, displayed as textarea, text or checkbox fields as appropriate.
Whether a varchar is displayed as a text or textarea input depends on its
maximum length, with the breakpoint determined by a configuration variable.
Smallints and tinyints are assumed to be booleans and are displayed as checkboxes.
Text descriptions are looked for in the lang files with the tag room.column_name,
eg room.coffee_machine, or users.phone enabling translations to be provided.
If not present, the column name will be used for labels etc.
[Note: smallints are assumed to be booleans because the boolean type in
PostgreSQL presents some problems in PHP when trying to process the results
of a query in a database independent way, so it is more convenient to use a
smallint instead of a boolean in PostgreSQL.]
As an example, to add a field to the room table recording whether or not
there is a coffee machine you would, in MySQL, add the column
coffee_machine tinyint(1)
to the room table and add the line
vocab["room.coffee_machine"] = "Coffee machine";
to the lang.en file and similarly for other languages as required. MRBS
should then do the rest and display your coffee machine field on the room
pages.
APPLICATION SETUP
---------------------------------------------------------------------------
Next, you will need to customize the file "config.inc.php"...
As a minimum you will need to set the timezone and the database variables.
Other settings can be changed by copying lines from systemdefaults.inc.php and
oasting them into config.inc.php. Do not edit systemdefaults.inc.php as it
will make it harder for you to upgrade when new versions are released.
1. Timezone
You must set the timezone to a valid value, a list of which can be found at
http://php.net/manual/en/timezones.php. Note that the timezone to use is the
timezone in which your meeting rooms are located, not the timezone of your
server in case they are different.
2. Database Settings:
First, select your database system. Define one of the following:
$dbsys = "mysql";
$dbsys = "mysqli";
$dbsys = "pgsql";
Then define your database connection parameters. Set the values for:
$db_host = The hostname that the database server is running on.
$db_database = The name of the database containing the MRBS tables.
$db_login = The database login username
$db_password = The database login password for the above login username
If the database server and web server are the same machine, use
$db_host="localhost". Or, with PostgreSQL only, you can use $db_host="" to
use Unix Domain Sockets to connect to the database server on the same machine.
By default, MRBS will use PHP persistent (pooled) database connections,
for better performance. Depending on your web server and database server
configuration, it is possible that this will cause MRBS to reach the maximum
number of connections allowed to your database, since each Apache child
process may keep a connection open. Then, users will randomly get errors
when trying connecting to MRBS. If you would rather use non-persistent
database connections, uncomment the line in "config.inc.php" which sets the
$db_nopersist variable.
If you want to install multiple sets of mrbs tables when only one
SQL database is available, or resolve table name conflicts, you have
to change the prefix of "mrbs_" for the tables in your database,
then you will need to set the value of:
$db_tbl_prefix = The table name prefix
3. Other Settings
Now go through systemdefaults.inc.php and see which other configuration settings
you would like to change. Do this by copying them to config.inc.php and changing
them there. This should make the task of upgrading to new releases easier as all
your site-specific configuration changes will be confined to config.inc.php.
There is a wide variety of settings that can be changed, including
- site identification information
- themes
- calendar settings
- booking policies
- display and time format settings
- private bookings settings
- provisisional bookings settings
- authentication settings
- email settings
- language settings
- report settings
- entry types
The comments in the systemdefaults.inc.php file should explain the purpose of the
various configuration variables and how to change them. (Note that some of the
settinngs can be set on a per-area basis through the area administration page in MRBS.
In this case the setting in the systemdefaults.inc.php/config.inc.php file defines
the default settings for new areas.)
The Help information is held in the site_faq files, one per language. You may well
want to customise it by editing the files.
CHANGING TEXT STRINGS
---------------------------------------------------------------------------
All the text strings used by MRBS, except those used on the Help page, are held in a
series of lang.* files, for example lang.en for English, or lang.fr for French. If
you want to change some of the text strings used by MRBS, for example change "Room"
to "Computer", then look for the appropriate string in the lang files and edit it.
INTERNATIONALISATION
---------------------------------------------------------------------------
From mrbs-1.2-pre2, MRBS is internationalised as long as the config
variable $unicode_encoding is set to 1 (which is the default setting).
If this is set, then MRBS serves all of its pages in UTF-8 and stores
everything in the database in UTF-8. This means that all languages work
together.
IF THIS DOES NOT WORK for you (your server may not have unicode support),
just set $unicode_encoding to 0. MRBS will run the old way, with pages
being served in an encoding based on the language, and the encoding of data
in the database being a mess of different encodings based on the users'
preferred language.
To use Unicode, php should be built with 'iconv' support ('--with-iconv'
directive), or have the iconv extension installed and enabled. On Windows,
if you are using PHP 5, iconv support is built-in.
For PHP 4 on Windows, three things are needed :
- iconv.dll file in in the system path. Either copy it from your
\%phpdir%\dlls\ directory into \%windir%\system32\ directory,
or add your \%phpdir%\dlls\ directory to your PATH environment variable.
(Note: for Microsoft IIS, you HAVE to copy iconv.dll into \%windir%\system32\)
- uncomment php_iconv.dll in php.ini.
- extension directory in php.ini have to be properly set to your actual
\%phpdir%\extensions\
Note: Upgrading mysql database from previous charsets to Unicode :
You can use convert_db_to_utf8.php script to convert text in the
database to UTF8, to use MRBS with $unicode_encoding set to 1. The
administrator should copy it into the web directory, run it (choosing
the encoding to convert from) ONCE, and then move it back out of the
web directory. We recommend you backup your database before running
this script if you are at all worried.
SECURITY NOTES!
---------------------------------------------------------------------------
You can configure your web server so that users can not obtain the ".inc"
files but this is not essential, since critical files containing your
database login and password use a ".php" extension like config.inc.php.
See your web server documentation on how to do this.
There is an Apache .htaccess file included, but Apache might ignore it because
of the "AllowOverride None" in your httpd.conf. Either change "AllowOverride
None" to "AllowOverride Limit", create a new <Directory> entry with the
contents of the .htaccess file in it, or add the contents of the .htaccess
to httpd.conf where it says "<Files ~ "^\.ht">". And then read the Apache
docs five or six times, until you know what you just did.
You may protect "config.inc.php" to only allow the web server to read it.
For example: # chown httpd config.inc.php; chmod 400 config.inc.php
The script "testdata.php" is for testing only. Do not leave it in a
directory accessible to your web server. Anyone running this will add a
large number of test entries to your database, regardless of
authentication, and book all your rooms to people you've never heard of.
$Id: INSTALL 1333 2010-04-21 08:46:28Z cimorrison $
