[[ux_install]]
Getting started
---------------

Prerequisites
~~~~~~~~~~~~~ 
 
To run UNICORE/X, you need the SUN or OpenJDK Java 6 (JRE or SDK). 
If not installed on your system, you can download it 
from http://java.oracle.com[http://java.oracle.com]

UNICORE/X has been most extensively tested on Linux-like systems, 
but runs on Windows and MacOS as well.

Please note that

 - to integrate into secure production environments, you will need 
access to a certificate authority and generate certificates for
all your UNICORE servers.

 - to interface with a resource management system like SGE or Torque,
you need to install and configure the UNICORE TSI.

 - to make your resources accessible outside of your firewalls, you should
setup and configure a UNICORE Gateway.

All these configuration options will be explained in the manual below.

Installation
~~~~~~~~~~~~

UNICORE/X can be installed from either a tar.gz or zip archive, or 
(on Linux) from rpm/deb packages.

To install from the tar.gz or zip archive, unpack the archive in a 
directory of your choice. You should then review the config files
in the conf/ directory, and adapt paths, hostname and ports. 
The config files are commented, and you can also
check xref:ux_configuration.

To install from a Linux package, please use the package manager of your
system to install the archive.

[NOTE]
===========
Using the Linux packages, you can install only a single UNICORE/X instance per machine (without
manual changes). The tar.gz / zip archives are self contained, and you can easily install
multiple servers per machine.
===========

The following table gives an overview of the file locations for both tar.gz and Linux bundles.


.Directory Layout
[options="header"]
|========================
| Name in this manual |tar.gz,  zip      | rpm                               | Description
| CONF | <basedir>/conf/    |/etc/unicore/unicorex             | Config files
| LIB  | <basedir>/lib/     |/usr/share/unicore/unicorex/lib   | Java libraries
| LOG  | <basedir>/log/     |/var/log/unicore/unicorex/        | Log files
| BIN  | <basedir>/bin/     |/usr/sbin/                        | Start/stop scripts 
| --   |  --                |/etc/init.d/unicore-unicorex      | Init script
|========================


==== Starting/Stopping

There are two scripts that expect to be run from the installation directory. To start, do
  
--------
cd <basedir>
bin/start.sh
--------

Startup can take some time. After a successful start, the log files (e.g. +LOG/startup.log+) 
contain a message "Server started." and a report on the status of any connections to 
other servers (e.g. the TSI or global registry).

To stop the server, do:
  
--------
cd <basedir>
bin/stop.sh
--------

Using the init script on Linux, you would do (as root)

----------------
etc/init.d/unicore-unicorex start|stop
----------------


==== Log files

UNICORE/X writes its log file(s) to the LOG directory. By default, log files are rolled daily, 
There is no automated removal of old logs, if required you will have to do this yourself.

Details about the logging configuration are given in xref:ux_logging.


==== Updating a 6.5.x installation

Starting with the 6.6.0 release, UNICORE components use a new security library called CANL 
(Common Authentication Library), which offers many additional options related to keystores, 
truststores, certificate revocation etc. We have also harmonised many settings, making the property
files easier to read and maintain.

Consequently many settings in the uas.config and wsrflite.xml files have new property keys, 
and new ones have been added. To update an existing installation, some effort will be required.

The general update procedure is presented below, with possible variations:

 1. Stop the old UNICORE/X server.
 2. Update the server package. This step mostly applies for RPM/DEB managed installations. For Quickstart installation
 it is advised to place the new UNICORE/X to a separate directory and replace the existing 'lib' folder by the new one.
 3. Port the configuration of the pre-6.6.0 server to the new syntax. It can be done in two ways:
   * Manually by applying all old values to the new template configuration. There are quite a few properties to be
   ported so this requires several minutes of work. The advantage of manual porting is that the new template files
   with new options and updated comments are used. Note: for RPM installations the new files will be named +*.rpmnew+.
   * Automatically, using UNICORE configurator. You have to install the +unicore-configurator+ package. It is included in
   Quickstart, for distributions install simply run appropriate command: +yum install unicore-configurator+ or
   +apt-get install unicore-configurator+. Using the configurator you can update the old files automatically:
      ** For RPM/DEB installations it is enough to run +unicore-config-update.py unicorex+.
      ** For Quickstart, specify the old config directory with the +-c+ option: +./unicore-config-update.py -c UNICOREX_CONFIG_DIR unicorex+.
   Carefully read the output of the program - there can be some problems reported.
   Option +-h+ provides help, with information about the usage: how to perform dry run, how to recover files
   from backup etc.
 4. Start the newly installed UNICORE/X.
 5. Verify the log files and fix any problems reported.


