PLEASE READ ALL OF THIS DOCUMENT BEFORE INSTALLING OR USING Xaraya

Please read UPGRADE.txt if you are upgrading an EXISTING Xaraya installation.
Ensure you check the VERSION CHANGES in UPGRADE.txt as you may need to update 
themes, templates or other areas in existing sites.

Detailed installation instructions can be found in the Xaraya User Guide, in 
the xarayaguide.txt file which is included in the docs directory of this 
release. The Guide will provide a clear understanding of installation and 
configuration of Xaraya.

Xaraya: adam_baum 1.2.1
=======================
Xaraya is an Open Source web applications framework.  Xaraya started out as a 
fork of PostNuke (http://www.postnuke.com). It has had a complete re-write 
from the ground up since it's beginnings.  Xaraya provides significant 
enhancements and functionality over it's predecessors and is in active, 
on-going development. Xaraya provides a stable and secure core, with a 
function rich API and powerful templating engine in place for third-party 
developers.

If you would like to help develop this software, please visit our homepage at 
http://www.Xaraya.com, or send email to info@xaraya.com.

You can also visit us in channel #support or #chat, on our IRC Server 
irc.xaraya.com.

Directories in the Xaraya distribution
======================================
The Xaraya distributions consist of the following directory structure:

- docs: The documentation for Xaraya and components.
        It is not necessary to copy this directory to the webserver.

- html: This directory contains the files and sub-directories that
        comprise Xaraya. For Xaraya to function, these files and
        sub-directories must be copied to the webserver.

        These files and sub-directories can be copied either to
        a sub-directory of the webserver's <webdir>
        (for example, <webdir>/<subdir>) or directly to the
        webserver's <webdir> (for example, <webdir>/).

If you install Xaraya into a sub-directory of the <webdir>, your users will 
have to type the sub-directory name in the URL. For example, if you install 
Xaraya into <webdir>/xaraya, your users will have to visit 
"http://www.yoursite.com/xaraya" to get to Xaraya. If you wish for Xaraya to 
exist in the <webdir> (so that users will visit "http://www.yoursite.com" to 
get to Xaraya), copy Xaraya's files & sub-directories to <webdir>.

- tools: This directory contains utility code. Noteworthy in this
         directory is the 'import' sub-directory, which contains
         utilities to import data from some popular Content Management
         Systems into Xaraya. It is not necessary to copy this
         directory to the webserver. Pieces you wish to use can
         be copied individually to the webserver. The 'modwizard'
         directory contains an xml/xslt application that can be
         used to generate a Xaraya module with standard functions.

New Installation
================
* Xaraya needs to be copied to your webserver. Not all files need to be copied
  - just the contents of the html subdirectory included in this package.

* The contents of that directory can be copied directly to your webserver 
  document root or they can be put in a subdirectory.

* Xaraya has a fully graphical install process to provide a simple set of steps 
  to get your site up and running.

* All sub directories on your webserver in the html/var/cache need to be 
  writable by the web server process, and executable, along with 
  the html/var/config.system.php file.

* Then, we can run the installation, depending on what you copied where:
    [everything in webdir]          http://www.foo.com/html/install.php
    [only html content in webdir]   http://www.foo.com/install.php
    [everything in subdir]      http://www.foo.com/bar/html/install.php
    [only html content in subdir]   http://www.foo.com/bar/install.php

* To install your Xaraya system, run the appropriate path to install.php 
  from your browser to start the installation process.  The exact URL depends 
  on your site, but the examples above should illustrate how to work out what 
  the correct path will be.

*  Read and carefully follow the instructions in the installation script 

*  Ensure any indicated directories and files are writeable by the 
   web server process for install.

*  The installer will create the required database tables and set up the account 
   for the person who will act as the administrator of the site.  Once complete 
   you should be able to start using your Xaraya site immediately 
   (if you need a new locale, please add it as described below).

    Please note that the option to "create the database" is related 
    to whether you need the installer to create the database itself first 
    or whether it can just go ahead and populate an already existing database.

*  Note - you do not have to install all modules at installation time. 
   Trying to installing many 3rd party modules during installation
   may lead to memory problems duing the install phase.
   Apart from the core modules, you can install additional modules easily
   at any time after installation.

*  After the upgrade has completed, remove upgrade.php and install.php
   from your web directory

*  Ensure that <xarroot>/var/config.system.php has appropriate permissions set
   for security, and is read only

Adding a locale (language and encoding):
---------------------------------------
* If you wish to add an additional locale for your Xaraya installation,
  download your preferred locale from http://www.xaraya.com/downloads/languages.
  For example for Spanish you need es_ES.utf8 locale

* Unpack the new locale to the Xaraya directory at var/locales

  NOTE: If you have var/locales/es_ES.utf8 directory
        already present after installation, delete it!
        It only contains installer translations.

* Create the directory var/locales/es_ES.utf8/php

* Make this directory writeable for the web server process

* Set the site encoding to es_ES.utf8 in the
  Base - Modify Config - Languages and Locales - Default Locale setting.

* If you need an additional locale with an encoding different 
  from UTF-8 please read this document
  http://www.xaraya.com/index.php/documentation/539


Caution
=======
It should be noted that Xaraya does not support any modification of the core 
tables (those that come with this Xaraya distribution) or direct access to 
the core database tables.  APIs are provided for developers to use for these 
purposes, so that future planned changes will have a minimal impact on 
third-party added functionality, and these APIs should be used at all times.

Please visit the #support channel for information on converting to Xaraya from 
CMS applications such as PostNuke or PHP-Nuke.

Common Installation Errors
==========================

- If you are having difficulties getting past the boot phase, specifically 
  errors about not being able to open the CACHEKEYS file for writing,
  try deleting the file:

    html/var/templates/CACHEKEYS

- Installer stops during boot phase.
  This could be a multitude of problems depending on
  your server configuration.  Please log the error messages to the Users
  newsgroup as well as http://bugs.xaraya.com .

- Trying to install too many 3rd party modules during the installation phase.
  This may lead to memory warnings or errors or 'blank' pages.
  Try installing with only the core or core plus base package modules. You can
  install additional modules at any time once installation has completed.

- The html/var/cache/rss and html/var/cache/templates need to be writable
  by the web server process, and executable, along with the config.system.php 
  file.

- If you have a problem with install of your databases, and you receive a 
  message:

  ErrorNo: 1142, Message:Database error while executing: 'CREATE INDEX 
  i_base_xar_uid ON xar_session_info (xar_uid)'; error description is: 'index 
  command denied to user: 'debeemster@localhost' for table 'xar_session_info''.

   This is an indication that you or your host does not allow the permission in
   the database to create indexes.  The system will suffer from slow performance
   without the DB index, and it is in your host's best interest to allow them.
