Installing Single-Node Fusion

Fusion is distributed as a gzipped tar file or as a compressed zip file. The package contains the Fusion API application, Fusion UI, the Connectors and a Solr installation.

This distribution can be used directly to run Fusion in single-server installations for developer instances or demonstration purposes. A production setup is likely to warrant a distributed setup, which is discussed further in the "Distributed Configuration" section.

Unpacking and extracting the Fusion archive

The following instructions are for an initial install of Fusion. If you already have installed a version of Fusion, you must stop any running Fusion processes and you should move the $FUSION directory, else it will be overwritten during install and unpacking. If you are upgrading Fusion, see the Fusion upgrade instructions.

Linux and Mac

To install Fusion on Linux or Mac
  1. Download the 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. Unpack the archive with tar xzf fusion.tar.gz (or tar xzvf fusion.tar.gz).

The resulting directory will be named "fusion". You can rename this if you wish.

Windows

To unpack the Fusion zipfile on Windows, you must use the freely available 7zip file archiver. Visit the 7zip download page for the latest version.

To install Fusion on Windows
  1. Download the zipfile for the latest version of Fusion and move it to where you would like it 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, you may need to check that you have permissions to extract folders on your system.

    The resulting directory has the same name as the basename of the zip file, such as "fusion-3.0.0", and it contains another directory named "fusion".

To install Fusion as a set of Windows services
  1. Run bin/install-services.cmd.

  2. Enter the name of the windows user that is used to launch this service.

    Remember the username is COMPUTERNAME\username or DOMAIN\username (if your computer is part of a Windows domain).

  3. Enter the user’s password.

  4. Enter the path to the directory containing the JDK to use for running the services.

Contents of the Fusion Home directory

The fusion directory is considered your Fusion Home, and is referenced as $FUSION throughout this documentation. See Directories and Logs for the contents of the $FUSION directory.

Single-server installation using the Solr instance included in the Fusion distribution

Solr is the default data store. Apache Spark is a cluster computing framework used by Fusion’s signals and aggregations services. Apache ZooKeeper is a distributed configuration service, synchronization service, and naming registry for large distributed systems. All Fusion components are registered and made discoverable with ZooKeeper.

As distributed, Fusion uses the instance of Solr and ZooKeeper included in the Fusion distribution both as the data store for Fusion’s own system and configuration information, as well as for all user collections. This is suitable for development purposes. For production deployments, ZooKeeper must be installed and run as a 3+ node ensemble.

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 the section Changing the Default Ports for more information if you need to modify the default Fusion ports before starting the application

Running 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).

Starting All Required Services

To run all required services from your Fusion Home :

  • ./bin/fusion start (Linux/Mac OS)

  • bin\fusion.cmd start (Windows)

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

This will start the bundled Solr and ZooKeeper instance, the Fusion API, the UI, and the Connectors. They each run in their own Jetty instances and on their own ports (see the section Changing the Default Ports for more on ports).

Starting Individual Services

Service Linux/Mac OS Windows Service URL

ZooKeeper + Solr

./bin/solr start

bin\solr.cmd start

http://localhost:8983/solr/#/

Fusion UI

./bin/ui start

bin\ui.cmd start

http://localhost:8764/

Fusion API + Jetty

./bin/api start

bin\api.cmd start

http://localhost:8765/api

Connectors

./bin/connectors start

bin\connectors.cmd start

http://localhost:8984/connectors/

Running Services In The Foreground

To run the above service in the foreground, use the "run" command-line argument in place of "start".

Stopping Services

Each of the applications listed above has a corresponding "stop" invocation. For example, to stop all services that have been previously started:

  • ./bin/fusion stop (Linux/Mac OS)

  • bin\fusion.cmd stop (Windows)

  • bin\stop-services.cmd (Stop all Fusion Windows services)

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".

Upstart log files for each service can be found in the /var/log/upstart directory. The service logs are logged to /opt/lucidworks/fusion/logs as normal.

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

sudo bash start.sh
sudo bash stop.sh

Windows Services

There is no support for running Fusion as a Windows service at this time.

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.properties. 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.

Accessing the system after start-up

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.

Troubleshooting

Fusion run script failures

Common problems that cause Fusion run scripts to fail:

  • Wrong Java version

  • Users has insufficient privileges for installation directory.

  • Java bin directory not in the PATH environment variable.

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

Check Java version

Fusion runs on JDK 1.8.

Fusion scripts use the environment variable JAVA_HOME. To check the setting of this variable, login 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:

>  $FUSION/bin/fusion stop

2016-01-15 17:42:58Z Stopping Fusion UI on port 8764
2016-01-15 17:43:09Z Stopping Fusion Connectors on port 8984
2016-01-15 17:43:21Z Stopping Fusion API Services on port 8765
2016-01-15 17:43:32Z Stopping Fusion Spark Worker on port 8769
2016-01-15 17:43:37Z Stopping Fusion Spark Master on port 8766
2016-01-15 17:43:42Z Stopping Fusion Solr on port 8983
2016-01-15 17:43:54Z 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 which is up and running, we see the following set of .pid files:

>  find 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.properties file.

More Help and Support