"Fossies" - the Fresh Open Source Software Archive

Member "mrbs-1.9.2/INSTALL" (14 Oct 2020, 24388 Bytes) of package /linux/www/mrbs-1.9.2.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "INSTALL": 1.9.0_vs_1.9.1.

    1         MRBS Installation Instructions
    2 
    3 
    4 
    5 REQUIREMENTS
    6 ---------------------------------------------------------------------------
    7 MRBS works with both MySQL (Version 5.5.3 and above) and PostgreSQL
    8 (Version 8.2 and above) systems. You must have at least PHP 5.4.0, with support
    9 for your chosen database system installed and working for this application.
   10 See the PHP (www.php.net), MySQL (www.mysql.com), and PostgreSQL
   11 (www.postgresql.org) sites for more info on setting these up.   You need
   12 to know how to install, secure, run, maintain, and back up your chosen database system.
   13 
   14 MRBS also requires that 'iconv' PHP extension, to provide
   15 internationalisation.
   16 
   17 You can run PHP either as a CGI or with a direct module interface (also called
   18 SAPI). These servers include Apache, Microsoft Internet Information Server,
   19 Netscape and iPlanet servers. Many other servers have support for ISAPI, the
   20 Microsoft module interface.
   21 You'll get better performance with PHP setup as a module.  Not only will you
   22 not have to deal with the CGI performance hit, but you'll be able to use PHP's
   23 database connection pooling. However, be careful that you don't exceed
   24 the maximum number of connections allowed to your database; with connection
   25 pooling PHP/Apache can potentially create a connection from each Apache
   26 child server to the database.
   27 Also many MRBS authentication schemes use basic HTTP authentication. These
   28 don't work if you run PHP as a CGI.
   29 
   30 If you are using PHP as an Apache module, you probably want to ensure that
   31 the Apache MaxRequestsPerChild is not set to 0, in case of undetected memory
   32 leaks in PHP or MRBS.
   33 
   34 OVERVIEW
   35 ---------------------------------------------------------------------------
   36 The steps involved in installing MRBS are:
   37 
   38 1.  Installing the MRBS files on your web server
   39 2.  Creating the MRBS tables in your database
   40 3.  Configuring MRBS
   41 
   42 After that you can then point your browser at MRBS and start creating areas
   43 and rooms.
   44 
   45 
   46 INSTALLING THE MRBS FILES
   47 ---------------------------------------------------------------------------
   48 To install MRBS, just unpack the distribution into a temporary directory,
   49 then copy the files in the "web" subdirectory into a new directory somewhere
   50 your web server can find them.
   51 
   52 If you are using a remote webserver, unpack the files into a temporary
   53 directory on your local machine and then upload them to suitable directory
   54 on your webserver, for example mydomain.com/mrbs
   55 
   56 If you are using a Unix/Linux webserver to which you have access, then
   57 an example of the installation might be:
   58 
   59 Unpack the software into a new temporary directory, something like this:
   60     $ tar -xvzf ~/download/mrbs-1.7.1.tgz       (or whatever version)
   61     $ cd mrbs-1.7.1                             (or whatever version)
   62 
   63 MRBS comes with a sample configuration file "web/config.inc.php-sample" -
   64 this should be copied to "web/config.inc.php" and configured for your
   65 site. The minimum you generally need to configure are the timezone
   66 (unless your PHP configuration already defines the timezone) and the
   67 database access details.
   68 
   69 If you are upgrading from a previous version of MRBS, you should consider
   70 copying your changes to the "config.inc.php" file into a new copy
   71 of config.inc.php copied from the new MRBS version's config.inc.php-sample.
   72 
   73 Now install MRBS by copying the contents of the "web" subdirectory of the
   74 distribution somewhere your web server can find it.  For example:
   75     $ cp -r web /var/lib/apache/htdocs/mrbs
   76 
   77 
   78 CREATING THE MRBS TABLES IN YOUR DATABASE
   79 ---------------------------------------------------------------------------
   80 For a new install:
   81 
   82 If you are using a remote webserver you should use your database
   83 administration program (eg phpMyAdmin in your control panel) to create the
   84 MRBS tables, by executing the contents of tables.my.sql.   For example, if
   85 you are using phpMyAdmin copy the contents of tables.my.sql into the SQL
   86 tab of phpMyAdmin and execute it as an SQL query.   This assumes that you
   87 have already created a database - if not you should create a database
   88 first.
   89 
   90 If you are using a Unix/Linux webserver to which you have access, then the
   91 procedure might be:
   92 
   93 [MySQL]         $ mysqladmin create mrbs
   94 [PostgreSQL]    $ createdb -E UTF8 -T template0 mrbs
   95 
   96 (This will create a database named "mrbs", but you can use any name.)
   97 
   98 Create the MRBS tables using the supplied tables.*.sql file:
   99 
  100 [MySQL]             $ mysql mrbs < tables.my.sql
  101 [PostgreSQL]        $ psql -a -f tables.pg.sql mrbs
  102 
  103 where "mrbs" is the name of your database (mentioned above).
  104 This will create all the needed tables.
  105 You may need to set rights on the tables; for PostgreSQL see "grant.pg.sql".
  106 If you need to delete the tables, for PostgreSQL see "destroy.pg.sql".
  107 
  108 The tables are now empty and ready for use.
  109 
  110 For an upgrade:
  111 
  112 If you are upgrading from MRBS 1.2-pre3 or later, your database will be
  113 upgraded automatically if necessary when you first run MRBS.   You will
  114 be prompted for a database (not MRBS) username and password with rights
  115 to create and alter tables.     Otherwise, please see the UPGRADE file.
  116 
  117 For a second installation or to use different table names:
  118 
  119 If you have table name conflicts or want to do a second installation
  120 and only have access to one database, then you can modify the 'mrbs_'
  121 prefix for the table names.
  122 
  123 In tables.*.sql you will need to change the table names and then follow
  124 the instructions above for creating the tables in your database.
  125 
  126 When editing config.inc.php, you need to change the table name prefix
  127 from "mrbs_" to the value you chose using the variable $db_tbl_prefix.
  128 
  129 WARNING: All of the .sql files are set up to use the 'mrbs_' prefix
  130          therefore you will have to edit them before you use them if you
  131          change the prefix for your tables.
  132 
  133 
  134 Maintenance:
  135 
  136 Be sure to back up your database regularly.
  137 For PostgreSQL, be sure to run the "vacuum" command regularly.
  138 You can clean out old entries from your database using the supplied SQL
  139 scripts purge.my.sql (for MySQL) and purge.pg.sql (for PostgreSQL). Read
  140 the comments at the top of the scripts before using them.
  141 
  142 
  143 ADDING EXTRA COLUMNS TO THE DATABASE TABLES
  144 ---------------------------------------------------------------------------
  145 It is possible to add extra columns to the entry, repeat, room and users
  146 tables, if you need to hold extra information about bookings, rooms and users.
  147 For example you might want to add a column in the room table to record whether
  148 or not a room has a coffee machine and you might want to record the phone
  149 numbers of users. (Note that the users table is only used if you are using
  150 the 'db' authentication scheme).   Similarly you might want to add a field
  151 to the entry and repeat tables to record the number of participants for
  152 a meeting.
  153 
  154 To add extra columns, just go into your database administration tool, eg
  155 phpMyAdmin, and add the extra columns manually.   MRBS will then recognise them
  156 and handle them automatically, displaying the information in the lists of rooms
  157 and users and allowing you to edit the data in the appropriate forms.
  158 
  159 NOTES:
  160 (1) if you are adding a field to the entry table you must add an
  161 identical field to the repeat table.   If you do not MRBS will fail with
  162 a fatal error when you try and run it.
  163 (2) names must consist of letters, numbers or underscores.  If you are
  164 using PostgreSQL then the name must begin with a letter or an underscore.
  165 If you are using MySQL then there is no restriction on the first character
  166 as long as it is in the permitted set, ie a letter, number or underscore.
  167 (Although MySQL will allow other characters in column names, MRBS imposes
  168 restrictions on the characters allowed in order to simplify the code. For
  169 a technical explanation see below).
  170 
  171 At the moment only text, varchar, decimal/numeric, int, smallint and tinyint
  172 columns are  supported, displayed as textarea, text, number or checkbox fields
  173 as appropriate.  Whether a varchar is displayed as a text or textarea input
  174 depends on its maximum length, with the breakpoint determined by a configuration
  175 variable. Ints are treated as integer types, as you would expect.   However
  176 smallints and tinyints are assumed to be booleans and are displayed as checkboxes.
  177 
  178 [Note:  smallints are assumed to be booleans because the boolean type in
  179 PostgreSQL presents some problems in PHP when trying to process the results
  180 of a query in a database independent way, so it is more convenient to use a
  181 smallint instead of a boolean in PostgreSQL.]
  182 
  183 Text descriptions are set in the config file using the $vocab_override variable
  184 using the appropriate language(s) and with the tag room.column_name,
  185 eg room.coffee_machine, or users.phone enabling translations to be provided.
  186 If not present, the column name will be used for labels etc.  If you are adding
  187 columns to the entry and repeat tables then you only need to add the
  188 entry.column_name tags:  you don't need to add a repeat.column_name tag.
  189 
  190 As an example, to add a field to the room table recording whether or not
  191 there is a coffee machine you would, in MySQL, add the column
  192 
  193 coffee_machine     tinyint(1)
  194 
  195 to the room table and add the line
  196 
  197 $vocab_override['en']['room.coffee_machine'] = "Coffee machine";
  198 
  199 to the config file and similarly for other languages as required.   MRBS
  200 should then do the rest and display your coffee machine field on the room
  201 pages.
  202 
  203 Extra options for custom fields:
  204 
  205 1)
  206 
  207 You can create dropdown boxes for a custom field by defining an
  208 entry in the configuration array $select_options. For example:
  209 
  210 $select_options['entry.conference_facilities'] = array('Video',
  211                                                        'Telephone',
  212                                                        'None');
  213 
  214 would define the 'conference_facilities' custom field to have three
  215 possible values.
  216 
  217 For custom fields only (will be extended later) it is also possible to use
  218 an associative array for $select_options, for example
  219 
  220 $select_options['entry.catering'] = array('c' => 'Coffee',
  221                                           's' => 'Sandwiches',
  222                                           'h' => 'Hot Lunch');
  223 
  224 In this case the key (eg 'c') is stored in the database, but the value
  225 (eg 'Coffee') is displayed and can be searched for using Search and Report.
  226 This allows you to alter the displayed values, for example changing 'Coffee'
  227 to 'Coffee, Tea and Biscuits', without having to alter the database.   It can also
  228 be useful if the database table is being shared with another application.
  229 MRBS will auto-detect whether the array is associative.
  230 
  231 2)
  232 
  233 You can specify that a field is mandatory. This will ensure that the
  234 user specifies a value for a field that may be empty, like a text box
  235 or a selection, as in 1) above. For example:
  236 
  237 $is_mandatory_field['entry.conference_facilities'] = true;
  238 
  239 would define the 'conference_facilities' custom field to be mandatory.
  240 In the case of a select field, this adds an empty value to the dropdown
  241 list.
  242 
  243 Making a checkbox field mandatory is possible and requires the
  244 checkbox to be ticked before the form can be submitted.   This can be
  245 useful for example for requiring users to accept terms of service or
  246 terms and conditions.
  247 
  248 3)
  249 
  250 You can also specify that a field is private, ensuring that the contents
  251 are only visible to yourself and the administrators.   For example:
  252 
  253 $is_private_field['entry.refreshments'] = true;
  254 
  255 would prevent the details of your refreshments being visible to other
  256 users - provided that private bookings are enabled.   See the section
  257 on private bookings in systemdefaults.inc.php for more information.
  258 
  259 
  260 Technical explanation of the restriction on column names for custom fields
  261 --------------------------------------------------------------------------
  262 // Column names for custom fields are used by MRBS in a number of ways:
  263 // - as the column name in the database
  264 // - as part of an HTML name attribute for a form input
  265 // - as part of a PHP variable name
  266 //
  267 // MySQL, PostgreSQL, HTML and PHP all have different rules for these tokens:
  268 // - MySQL: almost anything is allowed except that:
  269 //       - "No identifier can contain ASCII NUL (0x00) or a byte with a value
  270 //         of 255."
  271 //       - "Database, table, and column names should not end with space
  272 //         characters."
  273 //   (http://dev.mysql.com/doc/refman/5.0/en/identifiers.html)
  274 //
  275 // - PostgreSQL:  "SQL identifiers and key words must begin with a letter (a-z,
  276 //   but also letters with diacritical marks and non-Latin letters) or an
  277 //   underscore (_).   Subsequent characters in an identifier or key word can
  278 //   be letters, underscores, digits (0-9), or dollar signs ($). Note that
  279 //   dollar signs are not allowed in identifiers according to the letter of the
  280 //   SQL standard, so their use may render applications less portable. The SQL
  281 //   standard will not define a key word that contains digits or starts or ends
  282 //   with an underscore, so identifiers of this form are safe against possible
  283 //   conflict with future extensions of the standard."
  284 //   (http://www.postgresql.org/docs/8.1/interactive/sql-syntax.html#SQL-SYNTAX-IDENTIFIERS)
  285 //
  286 // - PHP:  "Variable names follow the same rules as other labels in PHP. A
  287 //   valid variable name starts with a letter or underscore, followed by any
  288 //   number of letters, numbers, or underscores. As a regular expression, it
  289 //   would be expressed thus: '[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*' "
  290 //   (http://php.net/manual/en/language.variables.basics.php)
  291 //
  292 // - HTML: "ID and NAME tokens must begin with a letter ([A-Za-z]) and may be
  293 //   followed by any number of letters, digits ([0-9]), hyphens ("-"),
  294 //   underscores ("_"), colons (":"), and periods (".")."
  295 //   (http://www.w3.org/TR/html401/types.html#type-cdata)
  296 //
  297 // In order to avoid complications with using names in each of these contexts,
  298 // we restrict custom field names to the set of names which conforms to all
  299 // four rules, taking into account the fact that when MRBS uses column names
  300 // in PHP and HTML it always prefixes them with a string beginning with a letter.
  301 // This gives us the rule that custom field names must consist of letters,
  302 // numbers or underscores.
  303 
  304 
  305 CONFIGURING MRBS
  306 ---------------------------------------------------------------------------
  307 Next, you will need to customize the file "config.inc.php"...
  308 
  309 As a minimum you will need to set the timezone and the database variables.
  310 Other settings can be changed by copying lines from systemdefaults.inc.php and
  311 areadefaults.inc.php and pasting them into config.inc.php.   Do not edit
  312 systemdefaults.inc.php or areadefaults.inc.php as it will make it harder for
  313 you to upgrade when new versions are released.
  314 
  315 Note that there are two different defaults files (systemdefaults.inc.php and
  316 areadefaults.inc.php) to draw attention to the fact that the settings in
  317 areadefaults just determine the settings for NEW areas.   Settings for existing
  318 areas are set using a web browser by following the "Rooms" link in MRBS.  (It
  319 can be a little frustrating editing the area settings to find that they have no
  320 effect on existing areas!)
  321 
  322 1.  Timezone
  323 
  324 You must set the timezone to a valid value, a list of which can be found at
  325 http://php.net/manual/timezones.php.   Don't forget to uncomment the line
  326 by removing the '//' at the beginning.   Note that the timezone to use is the
  327 timezone in which your meeting rooms are located, not the timezone of your
  328 server in case they are different.
  329 
  330 However, if you already have bookings in your system which were made under
  331 a different timezone (perhaps if you are upgrading from a previous version
  332 of MRBS where the timezone wasn't set explicitly and the timezone defaulted to
  333 that of the server) then you have two choices:
  334 
  335 (a) to set the timezone to be the same as the previous timezone.   This will
  336 ensure that all your existing bookings still appear correctly, but you will
  337 have to continue to put up with some minor inconveniences.   For example
  338 "Go to Today" will not always go to the today for your rooms, if you happen
  339 to be using MRBS at a time of day when the rooms are on one day but the
  340 timezone you have selected is on the day before or after.   Also if you are
  341 using the min and max book ahead facility then you will find that this is out
  342 by the difference between the timezone of your rooms and the timezone you have
  343 chosen.
  344 
  345 (b) to set the timezone to the timezone of your rooms, having first corrected
  346 the start and end times of all your existing bookings, in both the entry and
  347 repeat tables.   This is not a trivial exercise and you should back up your
  348 database before starting.   Note also that it is not necessarily as simple as
  349 adding or subtracting a fixed number of hours to existing bookings since the
  350 dates at which your rooms change between summer and winter time may be different
  351 to the dates at which your previous timezone made the DST change.   This can
  352 happen for example if your rooms are in Europe and your server is in the USA,
  353 as there is usually a week when Europe has changed but the USA has not.
  354 
  355 
  356 2.  Database Settings:
  357 
  358 First, select your database system. Define one of the following:
  359 
  360     $dbsys = "mysql";
  361     $dbsys = "pgsql";
  362 
  363 Then define your database connection parameters. Set the values for:
  364 
  365     $db_host =      The hostname that the database server is running on.
  366     $db_database =  The name of the database containing the MRBS tables.
  367     $db_login =     The database login username
  368     $db_password =  The database login password for the above login username
  369 
  370 If the database server and web server are the same machine, use
  371 $db_host="localhost". Or, with PostgreSQL only, you can use $db_host="" to
  372 use Unix Domain Sockets to connect to the database server on the same machine.
  373 
  374 By default, MRBS will not use PHP persistent (pooled) database connections.
  375 Persistent connections can sometimes give better performance, but they can
  376 also cause problems with transactions and locks.  For more details see
  377 http://php.net/manual/en/features.persistent-connections.php   Although
  378 MRBS is designed to work with persistent connections we recommend that you
  379 don't use them unless they give a significant performance boost.  To use
  380 persistent connections set
  381 
  382     $db_persist = TRUE;
  383 
  384 If you want to install multiple sets of mrbs tables when only one
  385 SQL database is available, or resolve table name conflicts, you have
  386 to change the prefix of "mrbs_" for the tables in your database,
  387 then you will need to set the value of:
  388 
  389     $db_tbl_prefix = The table name prefix
  390 
  391 
  392 3.  Other Settings
  393 
  394 Now go through systemdefaults.inc.php and areadefaults.inc.php and see which other
  395 configuration settings you would like to change.   Do this by copying them to
  396 config.inc.php and changing them there.   This should make the task of upgrading to
  397 new releases easier as all your site-specific configuration changes will be confined
  398 to config.inc.php.
  399 
  400 There is a wide variety of settings that can be changed, including
  401 
  402 - site identification information
  403 - themes
  404 - calendar settings
  405 - booking policies
  406 - display and time format settings
  407 - private bookings settings
  408 - provisional bookings settings
  409 - authentication settings
  410 - email settings
  411 - language settings
  412 - report settings
  413 - entry types
  414 
  415 The comments in the systemdefaults.inc.php and areadefaults.inc.php files should
  416 explain the purpose of the various configuration variables and how to change them.
  417 (Note that some of the settings can be set on a per-area basis through the area
  418 administration page in MRBS.   In this case the setting in the areadefaults.inc.php
  419 and config.inc.php files defines the default settings for new areas.)
  420 
  421 The Help information is held in the site_faq files, one per language.  You may well
  422 want to customise it by editing the files.
  423 
  424 
  425 CHANGING TEXT STRINGS
  426 ---------------------------------------------------------------------------
  427 
  428 All the text strings used by MRBS, except those used on the Help page, are held in a
  429 series of lang.* files, for example lang.en for English, or lang.fr for French.   They
  430 are overridden by the $vocab_override array in the config file.  If you want to change
  431 some of the text strings used by MRBS, for example change "Room" to "Computer", then
  432 look for the appropriate string in the lang files, remember its tag and set the
  433 $vocab_override variable in the config file.    For example
  434 
  435 $vocab_override['en']['ctrl_click'] = "Use Control-Click to select more than one computer";
  436 
  437 Doing it this way, rather than editing the lang files, will mean that when you upgrade to
  438 the next version of MRBS you will not have to re-edit the lang files.
  439 
  440 
  441 INTERNATIONALISATION
  442 ---------------------------------------------------------------------------
  443 
  444 From MRBS 1.4.6, MRBS is internationalised and uses UTF-8 throughout.
  445 MRBS will serve all of its pages in UTF-8 and stores everything in the
  446 database in UTF-8. This means that all languages work together.
  447 
  448 For MRBS to use Unicode, PHP must be built with 'iconv' support
  449 ('--with-iconv' directive), or have the iconv extension installed
  450 and enabled. On Windows, if you are using PHP 5, iconv support is built-in.
  451 
  452 Note: Upgrading MySQL database from previous charsets to Unicode :
  453 
  454   You can use convert_db_to_utf8.php script to convert text in the
  455   database to UTF8. The administrator should copy this file into the web
  456   directory, run it (choosing the encoding to convert from) ONCE, and then
  457   move it back out of the web directory. We recommend you backup your
  458   database before running this script if you are at all worried.
  459 
  460 
  461 PERIODS
  462 ---------------------------------------------------------------------------
  463 When using periods, MRBS stores bookings internally as one minute slots
  464 starting at 1200.    If once you have had your system up and running for
  465 a while find that you need to add a new period then you will need to
  466 adjust the times of your existing bookings unless your new period is at
  467 the end of the day.
  468 
  469 The simplest example is when you want to add a new period at the start of
  470 the day.   In this case you will need to run some SQL using phpMyAdmin or
  471 a similar program to move all bookings one minute later.  In this example
  472 the SQL required would be
  473 
  474 UPDATE mrbs_entry SET start_time=start_time+60, end_time=end_time+60;
  475 UPDATE mrbs_repeat SET start_time=start_time+60, end_time=end_time+60,
  476 end_date=end_date+60;
  477 
  478 having changed "mrbs_" to your table prefix if necessary.
  479 
  480 Before running this SQL you should of course backup your database.
  481 
  482 
  483 MULTISITE
  484 ---------------------------------------------------------------------------
  485 MRBS can be run in multisite mode by setting in the config file
  486 
  487 $multisite = true;
  488 
  489 In multisite mode a single instance of the MRBS code can serve a number of
  490 sites. Each site has its own config file in the sites/<sitename> directory
  491 which will override any settings in the global config file.  At a minimum
  492 the local config file will contain a table prefix for the site, but can also
  493 contain any other config settings including a theme and custom CSS.
  494 
  495 Individual sites can even have their own authentication methods, but note that
  496 authentication against WordPress multisite is not supported.
  497 
  498 
  499 SECURITY NOTES!
  500 ---------------------------------------------------------------------------
  501 You can configure your web server so that users can not obtain the ".inc"
  502 files but this is not essential, since critical files containing your
  503 database login and password use a ".php" extension like config.inc.php.
  504 See your web server documentation on how to do this.
  505 
  506 There are example Apache .htaccess files included, for different versions of
  507 Apache, but Apache might ignore a .htaccess file in your MRBS directory
  508 due to the setting of the "AllowOverride" directive in your web server
  509 configuration. Either change "AllowOverride None" to "AllowOverride Limit",
  510 or create a new <Directory> entry with the contents of the .htaccess example
  511 file in it for your MRBS installation. Then read the Apache docs five or six
  512 times, until you know what you just did.
  513 
  514 You may protect "config.inc.php" to only allow the web server to read it.
  515 For example:   # chown httpd config.inc.php; chmod 400 config.inc.php
  516 
  517 The script "testdata.php" is for testing only.  Do not leave it in a
  518 directory accessible to your web server. Anyone running this will add a
  519 large number of test entries to your database, regardless of
  520 authentication, and book all your rooms to people you've never heard of.