Installation instructions for Xtrack (for systems managers)

If you are upgrading from version 1 to version 2, go to upgrading.

The Xtrack database is a glorified notebook system that allows different people involved in a crystallographic project to remember what they have done, and find out what other people have contributed.

This document is for systems managers who wish to install the program at their site. Users do not need to install anything.

The main public access page is : http://xray.bmc.uu.se/xtrack

The user help file is available at : http://xray.bmc.uu.se/markh/php/xtrack_help.html
and the administrators guide at : http://xray.bmc.uu.se/markh/php/xtrack_admin.html
You may want to read these documents before proceeding with the installation.

System requirements

In order to install the program, you will need to be running PHP 4.3 or above and postgresSQL on your server.
These are available from http://www.php.net and http://www.postgresql.org respectively.

From PHP 5 the default setting for the "register_long_arrays" parameter was changed to to "Off", but this needs to be "On" for Xtrack to work.

And from postgres v8 the default encoding of databases changed, so you need to specify SQL_ASCII when creating databases.

There is a reported problem with using a Sun Blade-1000 with Solaris 9, whereby the database became curiously corrupted. The workaround is to buy a Linux box.

If you want support for the creation of thumbnails from uploaded image files, you will also need the GD library from http://www.boutell.com/gd/ installed. If you do not have this, then you must tell Xtrack about it by setting the variable $thumbDirName = ""; in the PHP source file.

If you want support for embedding crystallisation data into the EXIF header of uploaded crystal photos, you will need to install the pjmt package, and upload the Xtrack interface to this (mrh_exif_lib.tar).

Download

You will then need to download the Xtrack PHP interface and startup SQL files as one of the following tar files :
Xtrack latest version
Xtrack v2.0 (Beta)
Xtrack v1.02 (Stable)

Installation

1) Create a new directory on your web server called xtrack, and open the tar file there :
For example :
% mkdir xtrack
% cd xtrack
% tar xvf xtrack.tar

This should create the following files : xtrack.php, xtrack.sql, xtal.sql, xtrack_admin.sql, xtrack_logo.gif, update_db.csh, xtrack_help.html, xtrack_release.html and xtrack_install.html (this document).

2) Edit xtrack.php to set $db_user and $db_pass to the username and password for the postgress account that will be running your database. You can also set the default user and the device on to which backup dumps will be made.
Also, if you want the facility to upload user files to a central archive, change $archiveDir to point to a directory that is owned by the user under which your webserver runs (probably www) and is under the web server root. Then change archiveURL to a string that when appended to the hostname will give the equivalent URL of the archive directory.
If you want to be able to create control files to program a crystallisation robot, set $robotURL to point to a filtering program that can convert Xtrack's generic robot output to something more specific, and set $robotName to a string representing the name of your robot.

A user has pointed out that it is easiest to create a user called 'xtrack', and then use :
% sudo -u xtrack createdb -U xtrack xtrack
to create the db.

3) Using postgress, create a database called xtrack belonging to the user specified in the xtrack.php file.
For example :
% /usr/local/pgsql/bin/psql
CREATE DATABASE xtrack WITH ENCODING 'SQL_ASCII';
\q

The same helpful uswer has pointed out that this command failed for him, and so he used :
% createdb -E UTF-8 -U xtrack xtrack

4) You can edit xtrack.sql now to reflect your local preferences, but you may want to do a straight installation first, since it is easier to see what you want to change after running the interface. (Things like the names of beamlines that you use).

5) Feed xtrack.sql into postgress to set up all the data collection tables.
% /usr/local/pgsql/bin/psql -f xtrack.sql

6) Feed xtal.sql into postgress to set up all the crystallisation tables (from v2.0).
% /usr/local/pgsql/bin/psql -f xtal.sql

7) Feed xtrack_admin.sql into postgress to set up the Xtrack administrator's account.
% /usr/local/pgsql/bin/psql -f xtrack_admin.sql

8) Now point your browser at the xtrack.php script that you have installed, and you should be able to log in as "Admin", with the password given in the xtrack_admin.sql file. Then you can go to "preferences" and change password to something of your choice. (But note that it will be set back to the default if you later reload the SQL files.)

9) The variable $screen_lookup_url is set by default to point at the XtalScreens server in Uppsala, from where the recipes used in various commercial crystallisation screens can be fetched. If you really prefer to have that database locally (to be independent of our machines and the net, or because you want to add your own screen recipes), you can set the value to "local". Then you need to fetch the screens files from http://xray.bmc.uu.se/markh/php/export/screens.tar, untar them and feed screens.sql into the database. That will then read in the recipe files. However, using our server is probably the best option, since it will be more up-to-date.

10) And you're done. Now read the help files, create some users and enter some data.

11) It would be great if you could let us know that you have installed the system. Mostly out of curiosity, but it will also give us a chance to let you know about developments and bug fixes. We won't pass on your address, and we won't spam you.

12) If you are installing as part of the Vizier EU project, you will want to set "$vizier_flag = 1" in xtrack.php and read the following extra SQL definitions into your database : http://xray.bmc.uu.se/markh/php/export/xtrack_vizier_extensions.sql.txt

13) If you have made substantial modifications to the PHP code locally and you want to upgrade to v2.0, then an easy way to do that is to copy the crystallisation code from the new distribution into your old source. Contact me for details.

Upgrading from version 1 to version 2

Version 2 contains various small bug fixes, but also adds support for documenting crystallisation trials. See release notes for more details.

To upgrade to version 2, you need to get a new copy of xtrack.php (backwards compatible with your old system), and add some more tables to your database by reading in xtal.sql. Do the following :

1) Back up your old xtrack system.

2) create a new directory in which you will unpack the distribution, and move into that directory :
% mkdir xtrack_v2
% cd xtrack_v2

3) download this latest distribution file into that directory

4) Unpack the tar file :
% tar xvf xtrack.tar

5) Copy the new files to your old xtrack directory ("MY_XTRACK_DIRECTORY"), and move there :
% cp xtrack.php MY_XTRACK_DIRECTORY/
% cp xtal.sql MY_XTRACK_DIRECTORY/
% cd MY_XTRACK_DIRECTORY/

6) feed the file of new tables into your database :
% /usr/local/pgsql/bin/psql -f xtal.sql
(Note that there will be errors flagged, since the script starts off by trying to delete existing xtal tables, which do not exist the first time. Ignore these errors.)

7) Go home feeling pleased with yourself

Users help file

Administrators help file

Mark Harris