Installing the Rhapsody Engine on *nix

Before installing Rhapsody, refer to Datastore Setup for important information on configuring your datastore.

Installing the Rhapsody Integration Engine (Rhapsody) on *nix systems can be more complicated than installing on Windows® systems as *nix systems often do not have a GUI display available, requiring the display to be redirected or the console installer to be used. These systems can be broadly grouped into three categories:

Systems that cannot use a GUI display at all.
Systems that have XWindows available locally.
Systems that can export the display to a remote XServer.

Installers for the following Unix® environments are available:

AIX®
HP-UX
Linux®
Solaris

Run the executable for the operating system on which you are installing to start the installation:

Installing in Console Mode
Installing with XWindows
Installing with a Remote XServer

The installation must be run as a normal user, not the superuser or root. After the installation has completed, run the startup scripts as the superuser.

IOException: No space left on device

The var partition fills up when running the install, as install4j creates its temporary files under /var/tmp. If you encounter a 'java.io.IOException: No space left on device' error message when upgrading, ensure that you have at least 512MB in the /tmp or /var directories.

Installing in Console Mode

These instructions have been written using Linux® as an example.

To install the Rhapsody Engine on a *nix environment:

Copy the installer rhapsody-<version>-<operatingSystem>.sh to the *nix server using the Binary mode.

The installer file must be not be placed inside the existing engine's installation directory.
Navigate to the directory where the installer is located.
```
cd <installerLocation>
```

Change the installer to be an executable:

chmod +x rhapsody-<version>-<operatingSystem>.sh

Run the installer in the console mode using the -c argument:
```
./rhapsody-<version>-<operatingSystem>.sh -c
```

Press ENTER or o to continue:

Unpacking JRE ...
Preparing JRE ...
Starting Installer ...
This will install Rhapsody <version> on your computer.
OK [o, Enter], Cancel [c]

Specify the directory where you want to install Rhapsody, and press ENTER to continue.

Where should Rhapsody be installed?
[/<installation_directory>/orionhealth/rhapsody]

If the installer detects another installation, the following upgrade message is displayed:

Rhapsody Upgrade

A Rhapsody engine is already installed at this location. You can either
upgrade the existing installation or choose another location.

If you choose to upgrade it is strongly recommended that you backup your
existing configuration before continuing, including any custom
communication points or filters.

[Enter]

Press ENTER to continue. If you are upgrading from Rhapsody 5 or earlier, a datastore migration is performed. Refer to Configuration Migration for details. The following warning is displayed:

The Rhapsody configuration will be migrated to a versioned configuration
repository when first started after the upgrade. A backup of the
configuration will be kept in:
/<installation_directory>/orionhealth/rhapsody/rhapsody/data/config/migrated.

Warning: Upgrading removes all unknown files from the
installation directory. Ensure that you have a backup before proceeding.

Specify whether you wish to disable HTTP connections:

Do you want to disable HTTP connections?

Rhapsody allows both HTTP and HTTPS connections to the Management Console.
It is recommended that you only use HTTPS connections.

HTTPS can verify the authenticity of the server and prevent eavesdropping.
Disable HTTP connections to Management Console?
Yes [y], No [n, Enter]

Specify the location of the Data directory, and press ENTER to continue.

We recommend that you install the data files on a high-performance disk with a raid array. The disk must be fast and reliable as the messages are stored in the data files.
```
Where should the data directory be located?
[/<installation_directory>/orionhealth/rhapsody/rhapsody/data] 
```
Specify the initial and maximum memory that Rhapsody can use, and press ENTER to continue. JVM Maximum Heap memory provided must be greater than 512MB and not less than the JVM Initial Memory. When installing on a dedicated server, the JVM memory should be approximately half of the physical memory. For example, if the server has 3GB of RAM, allocate around 1536 MB.

The maximum heap size advised for 32-bit *nix environments is approximately 1200MB. If you have a larger heap size requirement, you must use a 64-bit operating system.
```
What memory settings should be used?
Specify the initial memory and the maximum memory to allocate to the Rhapsody Engine.
The recommended JVM memory allocation for a production environment can be
found in the "Rhapsody Hardware Recommendation Guide" document located
within the Documents folder.
JVM Initial Memory (MB)
[512]
 
JVM Max Memory (MB)
[1024]
```

Ensure that the default ports used by Rhapsody are free, and press ENTER to begin the installation. If the default ports are not available, enter alternative port numbers:

Port	Default Value	Description
IDE Port	`3041`	The Rhapsody IDE port.
IDE Broadcast Port	`4031`	The configuration broadcast/browse port to connect to the Rhapsody engine.
Secure Management Console Port	`8444`	The Management Console HTTPS port.
Secure Web Service Port	`8449`	Web Service API HTTPS port.

What port settings should be used?
Specify the ports that Rhapsody should use. These must be changed if they are not available.
IDE Port
[3041]
IDE Broadcast Port
[4031]
Secure Management Console Port
[8444]
Secure Web Service Port
[8449]

When the wizard finishes installing Rhapsody, the following message is displayed:
```
Finishing installation...
```

Installing with XWindows

If XWindows is available when installing the Rhapsody Engine, then the installation is very similar to that on Windows®. Launch the installer while XWindows is running to launch the GUI installer.

If the following error message (or similar) is displayed after launching the installer, the installer can fail to connect to the local XServer to host the display:

Could not display the GUI. This application needs access to an X Server.
If you have access there is probably an X library missing.
*******************************************************************
You can also run this application in console mode without
access to an X server by passing the argument \-c
*******************************************************************

The possible reasons are XWindows is not started or unavailable, or because symbolic links in the /usr/lib folder point to the incorrect location. If you are still unable to resolve the issue, select one of the other installation options instead.

Installing with a Remote XServer

If the *nix system does not have XWindows available locally, it is often possible to export the display to another machine, therefore allowing the GUI installer to be used. To do this, another machine with an XServer must be available to host the installer display. A second *nix system running XWindows can be used for this purpose, otherwise a number of XServers for Windows® are available, which can host the display of a *nix GUI application. One such XServer, contained with Cygwin, is available from http://www.cygwin.com/.

Once XServer has been started on the host machine, two commands must be run to export the display, one on the host and the other on the *nix machine.

Relax the security on the host machine so that it can host GUI applications on its XServer by running the following command:
```
xhost +
```
Redirect the GUI display from the Unix® machine to the host machine:
```
export DISPLAY=<host machine>:0
```
For example, if the IP address of the host machine was 192.168.1.54, then the command would be:
```
export DISPLAY=192.168.1.54:0
```
Some *nix systems require the export of the DISPLAY variable to be done in two stages as follows:
set DISPLAY=192.168.1.54:0 export DISPLAY
When the display has been exported, the installer can be launched normally.

Installing the Rhapsody Engine on *nix

Installing in Console Mode

Installing with XWindows

Installing with a Remote XServer

Related Topic