Union User Guide

Installation and Startup

In the default configuration of most operating systems, the following steps will install and start Union Server on port 9100:

  1. Decompress the Union Server distribution (.zip or .tar.gz file). A folder named /union/ is created.
  2. From the /union/ folder, run the following commands at the command prompt ("Terminal" on Mac):
    • On Mac, Unix, or Linux:
      chmod 775 *
      ./startserver.sh
    • On Windows:
      startserver.bat

If the preceding steps are unsuccessful, your system may need additional configuration. See Detailed Installation Instructions, following.

Detailed Installation Instructions

To install Union Server, decompress the Union Server distribution to a folder of your choice (referred to as UNION_HOME). The UNION_HOME folder contains the following scripts for starting and stopping the server

  • startserver.sh (Mac, Unix)
  • startserver.bat (Windows)
  • stopserver.sh (Mac, Unix)
  • stopserver.bat (Windows)

If you have purchased a Union licence key, follow these instructions to activate your licence.

To start Union Server, follow these steps:

  1. Add Java to your operating system's path or edit the start-server script to point to your java binary.
  2. Unix/Linux/Mac only: to ensure the startserver.sh and stopserver.sh scripts are executable, run the following command in the UNION_HOME directory:
    chmod 775 *
  3. From the command line, run the startserver script appropriate for your operating system (startserver.bat for Windows, startserver.sh for Unix/Linux/Mac). For example, the following command starts Union Server on Unix/Linux/Mac:
    ./startserver.sh

    Mac OSX 10.5 (Leopard) users note: the required version of Java (Java 1.6) is not the default version on Mac OSX 10.5. If you attempt to run Union under a version of Java older than 1.6, you will encounter the following error: "Exception in thread 'main' java.lang.UnsupportedClassVersionError". For information on running Java 1.6, see System Requirements.

Desktop users please note: closing the command prompt window (terminal) will shut down the server. On production Linux/Unix servers, the provided startserver.sh script will start Union Server as a background process, so the server will continue to run even after the user that started it logs off.

In the default configuration, Union Server starts a public gateway listening on port 9100 and an administration gateway listening on port 9110. To verify that the server started correctly, view log.txt, which is created in UNION_HOME. After a successful start, log.txt should contain log messages similar to the following:

2011-04-26 22:12:09,612 WARN  - ***********************************************
2011-04-26 22:12:09,612 WARN  - *** Starting Union Server 1.0.2 (build 498) ***
2011-04-26 22:12:09,613 WARN  - ***********************************************
2011-04-26 22:12:09,613 WARN  - UPC Version: 1.9.2
2011-04-26 22:12:09,613 WARN  - Java VM [1.6.0_17 from Apple Inc.]
2011-04-26 22:12:09,613 WARN  - Licence [Union Enterprise]
2011-04-26 22:12:09,710 WARN  - UNION_HOME set to [/Users/yourname/union/.]
...
2011-04-26 22:12:11,532 WARN  - Union Server 1.0.2 (build 498) Started....OK

Specifying Union Server's Maximum Memory Allowance

To limit the amount of memory used by Union Server, use the java command-line option "-Xmx". For example, to start Union Server with a maximum of 512 MB of memory, use the following command:

Mac/Unix/Linux:

java -Xmx512m -Dfile.encoding=UTF-8 -cp lib/union.jar:lib/stax-api-1.0.1.jar:lib/wstx-asl-3.2.6.jar net.user1.union.core.UnionMain start &

Windows:

java -Xmx512m -Dfile.encoding=UTF-8 -cp lib\union.jar;lib\stax-api-1.0.1.jar;lib\wstx-asl-3.2.6.jar net.user1.union.core.UnionMain start

Customize Your Configuration

Now that the server is running take a few minutes to adjust the following important system settings.

  1. Change Union Server's administration password! See Configuration.
  2. Determine what gateways you want running and on what IP addresses/ports. To allow clients to connect through firewalls, the server should be configured to accept connections over ports 80 and 443. See Gateways.
  3. Choose a log level. Union Server's default log level is DEBUG, which can be very verbose. Production deployments should set the log level to WARN or FATAL.

When you are done configuring Union Server, run the stopserver script. When the server has stopped, run the startserver script again and notice the changes in the log.