How to Configure and Install Xaraya 2.3.0

This page is here to guide you through the steps of configuring the Xaraya web applications framework for a NEW installation. If you are upgrading an EXISTING Xaraya 2.0.0 (or later) installation to Xaraya 2.3.0, please point your browser to upgrade.php and run the upgrade script.

For more support resources click on the first link in the header above. Once you have completed the simple steps outlined below, you should run the installer script by pointing your web browser at http://www.mydomain.com/install.php.

What is Xaraya 2.3.0

Xaraya is an Open Source web applications framework. It provides a stable and secure core, with a function rich API and powerful templating engine in place for third-party developers. Xaraya 2.3.0 is a major rewrite that offers enhanced performance with a smaller foorprint, more versatile functionality, easier usability and strict adherence to XHTML standards. 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.

Required Directories

top

Xaraya consists of three main components, each in its own folder:

html folder: contains all the elements that will be accessible by the web server.
lib folder: contains Xaraya and third party libraries. These include the Xaraya core code, the Blocklayout templating engine, and the Creole database middleware.
code folder: contains code elements, notably the modules your Xaraya installation will run.

The top level of your installation (the xaraya-2.3.0 folder) is called the root directory. For special situations the root directory can be redefined to as different directory on your server (see Custom Installations below).

To run properly your installation requires only the three folders listed above and their contents. All other contents of your unpacked installation file are for information only, or additional functionality for special situations, and can be safely removed.

Installing in a Solo Environment

top

Follow this installation procedure if you are running Xaraya on your own server and can configure your web host.

Unpack the distribution file you downloaded (since you are reading this you have already done that).
Place the folder xaraya-2.3.0 containing the distribution on your web server.
Configure your web server (www.mydomain.com) to make the html directory in your installation its root directory.
Point your web browser to www.mydomain.com/install.php and run the installation routine. The installation process takes 5-10 minutes, and you will be asked to make a number of decisions concerning your Xaraya site's configuration. Apart from defining the database your site will work with, all other configuration settings can be changed later. If you are unsure about a specific configuration, choose the defaults the installer provides.
Once the installation is successful, be sure to remove the file install.php in the html directory to avoid malicious use.

Installing in a Shared Environment

top

Follow this installation procedure if you are running Xaraya in a shared hosting environment and cannot configure your web document root directory.

Unpack the distribution file you downloaded (since you are reading this you have already done that).
Move the contents of the html directory one level up (at the same level as the lib directory). You can delete the html directory, which is now empty. If you want to create several instances of Xaraya (for different sites), copy the contents of the html folder to the top level rather than moving them. You can then take create another instance using the contents of the html folder as described further down.

Open the file var/layout.system.php. Uncomment (remove the initial double slashes) the lines

    //$systemConfiguration['rootDir'] = "";
    //$systemConfiguration['webDir']  = "";
    //$systemConfiguration['libDir']  = "lib/";
    //$systemConfiguration['codeDir'] = "code/";

Save the file modified var/layout.system.php.

Point your web browser to www.mydomain.com/install.php and run the installation routine. The installation process takes 5-10 minutes, and you will be asked to make a number of decisions concerning your Xaraya site's configuration. Apart from defining the database your site will work with, all other configuration settings can be changed later. If you are unsure about a specific configuration, choose the defaults the installer provides.
Once the installation is successful, be sure to remove the file install.php in the html directory to avoid malicious use.

Custom Installation

top

Xaraya lets you move the html, lib and code folders to different locations on your server. By moving the last two When creating such a custom layout you need to adjust the values in the var/layout.system.php appropriately. The following rules apply:

The value of $systemConfiguration['rootDir'] is the location of the root directory as an absolute location or relative to the file index.php. The root directory is notional and serves only as a reference point for the Xaraya components. It does not need to have any specific name or even be associated with Xaraya. Examples on a Linux server:
```
    $systemConfiguration['rootDir'] = '/usr/local/';    absolute location on the server
    $systemConfiguration['rootDir'] = '../';            location relative to index.php
                                            
```
The values of $systemConfiguration['webDir'], $systemConfiguration['libDir'] and $systemConfiguration['codeDir'] must correspond to the locations of the html, lib and code directories respectively relative to the root directory.

Renaming the Document Root

top

The document root directory (the directory containing the file index.php) in Xaraya's default install is named 'html'. In many shared hosting environments the document root directory has a different name, such as 'public_html'. To change the name of the Xaraya document root:

In the var/layout.system.php file, change all references to 'html' to whatever the directory's new name is to be, e.g..

$systemConfiguration['rootDir'] = "../";
$systemConfiguration['webDir']  = "html/";
$systemConfiguration['libDir']  = "lib/";
$systemConfiguration['codeDir'] = "html/code/";

$systemConfiguration['rootDir'] = "../";
$systemConfiguration['webDir']  = "public_html/";
$systemConfiguration['libDir']  = "lib/";
$systemConfiguration['codeDir'] = "public_html/code/";

Rename the document root directory in your Xaraya install, or move the contents of the document root directory to the directory provided by the hosting environment.
Restart the web server.

Note that in the "flat install" configuration in var/layout.system.php, the document root directory is given as "". In such cases where the directory is not explicitly named, no changes to the layout file need to be made.

Installing Multiple Sites

top

To be added

Troubleshooting and Caveats

top

Unless you know what you're doing, never separate the contents of the lib, core or html folders
Make sure the appropriate files in the var directory are writable by the web server. The installer will complain if it finds that is not the case. If you are translating, be sure that your locales (files and subdirectories under var/locales) are writable.
code folder: contains code elements, notably the modules your Xaraya installation will run.
Linux installations: if you are using symbolic links, make sure they are used both for the code and lib directories. Otherwise you may get loading exceptions in some situations.

Legacy Support

top

Xaraya 2.3.0 provides limited legacy support for Xaraya 1.x modules. You can enable legacy support by checking the appropriate checkbox in the Base module Modify Config page (Other tab). Legacy support covers:

Xaraya 1.x function calls that have been deprecated.
Non-numeric entities (e.g.  )
Missing xartemplate tags in the beginning and end of templates.
Xaraya 1.x blocks code
Support for "uid" in core functions
Data storage in the array dataproperty
Some Xaraya 1,x dataproperty validation schemes (dropdowns)
Templates with .xd extensions
Old versions of the Dynamicdata tags

Please note that enabling legacy support will result in a small performance hit. Legacy support cannot be guaranteed in future versions of Xaraya 2

Xaraya Readme - Welcome to the Xaraya Web Applications Framework