.-----------------.
| Xortoth Install |
`-----------------'
	
(c) 1999-2002 Dr. Alex M. Clark
Release as copyleft, under the Gnu Public License (see www.gnu.org).

The homepage of this project can be found at:

	http://crk.sourceforge.net
	

Part 1
------

Install Apache, and PHP4. Make sure files with the .php extension in WWW
directory of choice are configured to run through the PHP module.

Install MySQL, and ensure that the daemon is running. Also make sure that
PHP4 is configured with the XML DOM and MySQL data access.

Part 2
------

Copy the PHP files in this package to an appropriate subdirectory (such as
/var/www/html/CRK). Note the URL access path for FatClient.php, e.g.
http://servername/CRK/FatClient.php).

Part 3
------

Create a MySQL database specifically for this purpose (or more than one,
for multiple Realms). Ensure that there is a user created with standard
access to the database (read, write, create table privileges).

See database_setup.txt for more detailed instructions and recommendations
as to how to go about this.

Part 4
------

In the same directory which contains the PHP pages, there should be a file
called "datasources"; if there is not already, create one. The format of
the file is comma delimited, and a hash at the beginning of each line
denotes a comment:

	# username,password,database,host
	XORUSER,PASS,XORTOTH,foo.bar.com

Alter the four fields as necessary to suit your installation. Note that the
third field is used as the distinguishing field when the page selects a
database. Add an additional line for each additional database to be used as
a Xortoth Realm.
	
Note that the password is stored in plaintext in this file, so it is
recommended not to make this file available for viewing via the webserver,
most especially if the MySQL port (3306) is not firewalled from the greater
internet.

Part 5
------

For each of the Realms/databases so configured above, formulate a URL to
access it. For example, if the pages were located in /var/www/html/Xortoth,
and the web root was /var/www/html, a valid base URL might be:

	http://localhost/Xortoth/FatClient.php
	or http://foo.bar.com/Xortoth/FatClient.php
	
The page that handles all the XML webservice-style requests used by the
other CRK programs (Xykron, Xentark and Xuru) is FatClient.php. The other
pages are either "include files", or the beginnings of a thin client
equivalent.

If there is just one database, the above URL examples would be complete;
however, if two databases were used, and they were called "xortoth1" and
"xortoth2", they could be distinguished by the URLs:

	http://localhost/Xortoth/FatClient.php?db=xortoth1
	and http://localhost/Xortoth/FatClient.php?db=xortoth2

The immediate place to use these URLs is in Xykron, under the Xortoth/Setup
dialog box. Within the Network tab, fill in the four fields:

	URL
	Realm Name
	Username
	Password
	
The URL part has just been described. Realm Name is arbitrary, but should
be a short string (e.g. "remote", "xortoth", etc); they should not be
duplicated within the settings. 

The Username and Password refer to the Realm user, not the database user.
Currently this is inactive, so enter anything (e.g. "foo", "bar"). This
minor security hole will be addressed in the near future ;-)

The Xykron settings are written to ~/.Xykron/Xykron.xml, which may
optionally be edited by other means. If you intend to use Xuru, you will
need to edit the ~/.Xuru/Xuru.xml file, and enter the URLs for any Xortoth
Realms which are to participate.

Major TO DO Items
-----------------

Security: Currently Xortoth has _no_ security at all. Anybody who can
obtain the URL can perform all the data functions via the Question/Answer
protocol. There are plans for adding new tables and fields for users,
passwords, groups, permissions, etc; implementation will begin soon.

Thin Client: This may be in the slightly less near future, but there are
some nebulous plans to produce a browseable interface to CRK data managed by
Xortoth. This will likely start out as read-only plain vanilla HTML, but
may progress to a fully functional computational materials suite with Java
applets and all - who knows where that'll lead.

Transactions: Presently the "MyISAM" tables are used, which are the
simplest type, and do not support transactions; table locking is used
instead. This is considered quite an adequate solution for the present
time, but at a later date the preferred type may be changed to
transactional data management.

Cheminformatics: Very long term; CRK does not presently aspire to
providing large, highly scalable data management features, but evolution
of needs and demands may eventually move it in that direction. The present
webservice/database model is both simplistic, non-rigid, and probably not
up to the task of managing more than a few thousand objects, so
restructuring will have to be contemplated at some point.

- AMC. 23/Apr/03
