Installing Single-Node Fusion

The Fusion distribution can be used to run a single-node installation for purposes of development, demonstration, or evaluation.

The following instructions are for an initial installation of Fusion. If you have already installed a version of Fusion, see the Fusion upgrade instructions.

Out of the box, Fusion uses the instances of Solr, ZooKeeper, and Spark that are included in the Fusion distribution. See the release history to find out which versions of Solr, Spark, and ZooKeeper are included in each Fusion release. To use Fusion with your existing Solr installations, see Integrating with existing Solr instances.

Note
For production deployments, ZooKeeper must be installed and run as a 3+ node ensemble.

Unix installation

Fusion for Unix is distributed as a gzipped tar file.

To install Fusion on Linux or Mac
  1. Download the fusion-version.x.tar.gz file for the latest version of Fusion and move it to where you would like it to reside in your filesystem (if you would like to use Upstart for process management, you must install Fusion in /opt/lucidworks).

  2. Become the user that will run Fusion.

    Important
    Do not run Fusion as the root user.
  3. Change your working directory to the directory in which you placed the fusion-version.x.tar.gz file, for example:

    $ cd /opt/lucidworks

  4. Unpack the archive with tar -xf (or tar -xvf), for example:

    $ tar -xf fusion-version.x.tar.gz

    The resulting directory is named fusion. You can rename this if you wish. This directory is considered your Fusion home directory. See Directories and Logs for the contents of the fusion directory.

Starting Fusion

All Fusion start scripts must be executed by a user who has permissions to read and write to the directories where Fusion is installed. These scripts don’t need to be run as root (or sudo), nor should they be. Use a suitable id, or create a new one, and then ensure that it owns the directory where fusion resides, (e.g. /opt/lucidworks).

To start all required services

./bin/fusion start

To start services individually
  • Fusion API Services:

    ./bin/api start

  • Connectors Services:

    ./bin/connectors start

  • Solr:

    ./bin/solr start

  • Spark Master:

    ./bin/spark-master start

  • Spark Worker:

    ./bin/spark-worker start

  • Fusion UI:

    ./bin/ui start

  • ZooKeeper:

    ./bin/zookeeper start

For information about default ports, see Default Ports.

Running Fusion In The Foreground

To run Fusion or any of its services in the foreground, use the run command-line argument in place of start.

Stopping Fusion

To stop Fusion or any of its services, use the stop command-line argument in place of start.

Ubuntu Upstart Scripts

Under Ubuntu 12.04 LTS or newer we support Upstart for process management. This requires Fusion to be installed in the /opt/lucidworks/ directory.

To configure upstart, run the following commands:

$ cd init/upstart
$ sudo bash install.sh

If this complains with no JAVA_HOME set, replace sudo with sudo -E. Then you can use the service command to control the server:

$ sudo service fusion-solr start
$ sudo service fusion-api start
$ sudo service fusion-connectors start
$ sudo service fusion-ui start

and similarly use stop and status.

Logfiles for Fusion services are found in directories under fusion/var/log.

Upstart log files for each service are in the /var/log/upstart directory.

For convenience, you can start/stop all services with Upstart using:

$ sudo bash start.sh
$ sudo bash stop.sh

Windows installation

Fusion for Windows is distributed as a compressed zip file. To unpack the Fusion zip file on Windows, you can use a native compression utility or the freely available 7zip file archiver. Visit the 7zip download page for the latest version.

To install Fusion on Windows
  1. Download the zip file for the latest version of Fusion and move it to where you would like Fusion to reside in your filesystem. It will appear as a compressed folder.

  2. Unpack the archive. In most cases, you need only right-click and choose "Extract all…​". If you don’t see this option, check that you have permissions to extract folders on your system.

    The resulting directory has the same name as the base name of the zip file, such as fusion-2.1.0, and it contains another directory named fusion. This directory is considered your Fusion home directory. See Directories and Logs for the contents of the Fusion home directory.

Fusion releases earlier than 3.0 do not support installation as a Windows service.

Starting Fusion

All Fusion start scripts must be executed by a user who has permissions to read and write to the directories where Fusion is installed. These scripts don’t need to be run as root (or sudo), nor should they be. Use a suitable id, or create a new one, and then ensure that it owns the directory where fusion resides, (e.g. /opt/lucidworks).

To start all required services
  • bin\fusion.cmd start

  • bin\start-services.cmd (Start all Fusion services as Windows services)

To start services individually
  • Fusion API Services:

    bin\api.cmd start

  • Connectors Services:

    bin\connectors.cmd start

  • Solr:

    bin\solr.cmd start

  • Spark Master:

    bin\spark-master.cmd start

  • Spark Worker:

    bin\spark-worker.cmd start

  • Fusion UI:

    bin\ui.cmd start

  • Zookeeper:

    bin\zookeeper.cmd start

For information about default ports, see Default Ports.

Running Fusion In The Foreground

To run Fusion or any of its services in the foreground, use the run command-line argument in place of start.

Stopping Fusion

To stop Fusion or any of its services, use the stop command-line argument in place of start.

Accessing the system after startup

Once the services have been started, you can access the Fusion UI at http://localhost:8764/ (replace 'localhost' with your server name or IP if needed). The first time you access the system, you must first set the admin password and agree to the Fusion terms. This is followed by an optional registration step. After this, Fusion displays the main UI page.

If you can’t access the system, see the Troubleshooting section below. Checking System State shows how to inspect Fusion services.

Ports

To run Fusion as a single-server installation, the following ports should be available and not used by other applications or services:

  • 8764

  • 8765

  • 8983

  • 8984

See Default Ports if you need to modify the default Fusion ports before starting the application.

Installation with an existing Solr instance or cluster

Fusion supports Solr versions 4.4 and higher. Solr 4.6.0 or 4.7.0 are not supported, as they contain severe bugs that will impact the ability of Fusion to work with your Solr system.

If installing Fusion to work with an existing Solr instance, either in SolrCloud mode or standalone, you should install Fusion as described above. You should start each of the services as described above.

Once Fusion installation is complete, you can register your existing Solr installation with Fusion to be able to use the two systems together. For details on how to do that, see the section Search Clusters.

Installation on multiple servers and production configurations

Solr and Fusion both communicate with a single external ZooKeeper instance to maintain state and store configuration files.

When designing a production service, there are many possible architectures and configurations, depending on existing operational practices and infrastructure, and expected load on the application. A typical architecture for a medium load could be:

  • A SolrCloud cluster on 3 machines, with a ZooKeeper instance and Solr instance on each

  • A Fusion installation installed on 2 additional hosts (for system failover).

To install Fusion on multiple servers, copy the Fusion archive package (either .tar.gz or .zip) to each server and unpack it. The Fusion start scripts must be modified as follows:

  • The configuration must be changed to point to the external ZooKeeper ensemble.

  • The embedded ZooKeeper instance that ships with Solr must be disabled.

The Fusion ZooKeeper instance is defined in the file fusion/conf/config.sh (or config.cmd) in variables FUSION_ZK and FUSION_SOLR_ZK. These configuration scripts are invoked from the file fusion/conf/common.sh (for Linux/Mac OS) and fusion\conf\common.cmd (for Windows) files. In Fusion releases prior to 1.2, these variables are defined in the common.sh (or common.cmd) file itself. These variables must be changed to the the list of server port pairs that make up the ZooKeeper ensemble, e.g.:

FUSION_ZK=zkserver1:2181,zkserver2:2181,zkserver3:2181

These edits must be done for each Fusion instance. Once configured, start each instance using the start command: fusion/bin/fusion start.

Troubleshooting

Fusion run script failures

Common problems that cause Fusion run scripts to fail:

  • Wrong Java version

  • Users have insufficient privileges for the installation directory.

  • Java bin directory not in the PATH environment variable.

  • Some Fusion services may already be running, or registered as running.

  • Roaming IP address; try uncommenting this line in fusion/conf/fusion.properties:

    default.address = 127.0.0.1

Check Java version

Fusion runs on JDK 1.8. See System Requirements.

Fusion scripts use the environment variable JAVA_HOME. To check the setting of this variable, log in to the account used to run Fusion, and check that this variable is set to the proper value. On a linux, Mac, or other Unix system, use the following command:

echo $JAVA_HOME

On Windows, the command is:

echo %JAVA_HOME%

Fusion scripts execute both the java and javac commands. To check the Java version invoked by these commands, run the following commands from a shell or terminal window:

java -version
javac -version

Clear browser cache

If a previous version of Fusion was accessed in the browser with the same URL as that of the newly installed version of Fusion, then there may be old pages and/or cookies in the browser cache. A hard page refresh will clear old pages from the browser cache. If clearing the page cache doesn’t solve this problem, clear session cookies as well.

Stop / Clean-up / Start

If script fusion/bin/fusion start completes without reporting an error, but the Fusion UI displays a message that it can’t find Collections or Datasources, this may be due to Fusion services not being able to communicate properly (via ZooKeeper). This can happen with developer deployments running on a laptop if the network connection changes or is interrupted, especially when using the embedded ZooKeeper instance that is bundled with Fusion.

In this situation, you should stop Fusion, inspect the system processes and if necessary, manually terminate running processes and cleanup .pid files to bring the system back to a clean state, then start Fusion once again.

Although the Fusion run script bin/fusion provides a restart option, the restart option assumes a correctly functioning system and can’t always recover from system failure.

To stop Fusion:

Run the script fusion/bin/fusion with the argument stop:

$ cd /path/to/fusion
$ ./bin/fusion stop
2016-10-04 20:18:30Z Stopping Fusion UI on port 8764
2016-10-04 20:18:42Z Stopping Fusion Connectors on port 8984
2016-10-04 20:18:53Z Stopping Fusion API Services on port 8765
2016-10-04 20:19:05Z Stopping Fusion Spark Worker on port 8769
2016-10-04 20:19:10Z Stopping Fusion Spark Master on port 8766
2016-10-04 20:19:15Z Stopping Fusion Solr on port 8983
2016-10-04 20:19:27Z Stopping Fusion ZooKeeper on port 9983

After stopping Fusion, you should make sure that no Fusion services are running. When the Fusion scripts start a Fusion service, they record the process id in a .pid file in the directory fusion/var. For a Fusion instance that is up and running, we see the following set of .pid files:

>  find /path/to/fusion/var -name "*.pid" -print

fusion/var/api/api.pid
fusion/var/connectors/connectors.pid
fusion/var/solr/solr.pid
fusion/var/spark-master/spark-master.pid
fusion/var/spark-worker/spark-worker.pid
fusion/var/ui/ui.pid
fusion/var/zookeeper/zookeeper.pid

The above output shows the set of .pid created by a single Fusion instance running with embedded ZooKeeper and Solr.

But if no Fusion services are running, there shouldn’t be any .pid files. In the case that all services have been stopped, but there are still some .pid files found, these files should be deleted before starting Fusion.

Inspect the logfiles

If none of the above help, inspect the Fusion logfiles in directory fusion/var/log.

Logfile names that start with "oom" indicate out-of-memory problems. You may need to increase the amount of memory allotted to that service. The amount of memory allotted to each kind of Fusion service is controlled by environment variables which are set in the fusion/conf/config.sh (linux, Mac, Unix) or fusion/conf/config.cmd (Windows) file. These variable names consist of the service name followed by "_JAVA_OPTIONS", e.g.:

API_JAVA_OPTIONS=(-Xmx1g -Xss256k -XX:MaxPermSize=256m -Dapple.awt.UIElement=true)

More Help and Support