Apache Solr on Managed Flex Servers

Solr is an open-source search platform written in Java and a development that is part of the Apache Lucene project. One of the main applications Solr offers is optimized full-text search.

This guide explains how to run Solr on your Managed Flex Server.

Requirements

The following requirements must be met to run Solr:

• Java Runtime Environment (JRE) – available on your Managed Flex Server and updated by us regularly
• Solr can be run on Managed Flex Server M products and higher.

Installation and getting started

To complete the following steps, you must be logged into your Managed Flex Server via SSH.

To provide you with a clear overview of your installed applications, we recommend installing your applications in an app folder located in your customer home directory. In this Solr installation and configuration guide, we will save the application under ~/app/solr. To create this folder structure, use the following command:

mkdir -p ~/app/solr

Downloading Solr

To download Solr, navigate to the application directory you just created:

cd ~/app/solr

Then download and unzip the latest version from the Solr-Website:

			wget https://downloads.apache.org/lucene/solr/x.x.x/solr-x.x.x.tgz -O /tmp/solr.tar.gz
 tar -xzf /tmp/solr.tar.gz -C ~/app/solr
 rm -rf /tmp/solr.tar.gz

We recommend creating a symlink from ~/app/solr/current to the downloaded folder to avoid having to work with version numbers in the configuration files. To create this symlink, enter the following command:

ln -s ~/app/solr/solr-x.x.x ~/app/solr/current

Configuring Solr

To ensure Solr only listens to 127.0.0.1, you must set the following option in the configuration file ~/app/solr/current/bin/solr.in.sh:

SOLR_OPTS="$SOLR_OPTS -Djetty.host=127.0.0.1"

Otherwise, Solr will listen to all of the server’s IP addresses, which would then make Solr accessible over the internet.

Testing Solr

This section describes how you start Solr, save a document in it and then retrieve it again.

After successfully installing and configuring Solr, start it to carry out some initial tests in the foreground (argument -f):

~/app/solr/current/bin/solr start -f

Because Solr is running now, in a second SSH shell you can set up a Solr core where you can save and retrieve the documents. Enter the following command to create a Solr core named example-core.

_JAVA_OPTIONS="-Xms32m -Xmx256m" ~/app/solr/current/bin/solr create_core -c example-core

A Solr core references an index with the corresponding configurations and transaction log files.

Saving a document in Solr

The following PHP script, which is saved at ~/app/solr/hello-world-insert.php, lets you save a document in Solr using the Solr PHP library. The document is created with the ID 1, the category example, and the text “Hello World!”.

<?php 

$options = array
(
    'hostname' => '127.0.0.1',
    'port' => 8983,
    'path' => 'solr/example-core'
);

$client = new SolrClient($options);

$doc = new SolrInputDocument();

$doc->addField('id', 1);
$doc->addField('cat', 'example');
$doc->addField('text', 'Hello World!');

$updateResponse = $client->addDocument($doc);
$client->commit();

print_r($updateResponse->getResponse());

?>

The PHP script can be executed as follows and the document is saved in Solr:

php ~/app/solr/hello-world-insert.php

Searching for the document in Solr

To search for documents in Solr, you can use the following PHP script, which is saved at ~/app/solr/hello-world-search.php. In this example, a search is performed for all documents that fall under the example category. When the search finds a document, it returns the fields id, cat and text.

<?php
			
$options = array
(
    'hostname' => '127.0.0.1',
    'port' => 8983,
    'path' => 'solr/example-core'
);

$client = new SolrClient($options);

$query = new SolrQuery();

$query->setQuery('cat:example');

$query->setStart(0);

$query->setRows(50);

$query->addField('id')->addField('cat')->addField('text');

$query_response = $client->query($query);

$response = $query_response->getResponse();

print_r($response);

?>

You can now also execute this script to test the functionality:

php ~/app/solr/hello-world-search.php

Integration

Using Custom Service Control

So far, you have been starting your application manually from the shell. While this is an easy method for testing and development purposes, it is not an option for production operations. The Custom Service Control (CSC) can handle operations and the automatic management of your application, e.g. starting and stopping it when performing maintenance on your server.

If you have not used the CSC before, start by opening it to create the necessary configuration files:

hpservices supervisord start
supervisord successfully started

Configuring Solr in the CSC is fairly simple. Set up a new custom service for Solr:

hpservices supervisord add solr
successfully created dir for solr: /home/username/.services/supervisord/solr
successfully created dir for solr: /home/username/.services/supervisord/solr/log
supervisord service config file written: /home/username/.services/supervisord/solr/service.conf

A configuration framework is created in the file ~/.services/supervisord/solr/service.conf for the new service. For Solr, you must only modify the command. You can leave all other suggested values alone (delete the semicolon at the beginning of the line).

[program:solr]
command=%(ENV_HOME)s/app/solr/current/bin/solr start -f
directory=%(ENV_HOME)s/app/solr/ ; directory to cwd to before exec (default no cwd)
autostart=true ; start application at supervisord start (default: true)
stopwaitsecs=10 ; max num secs to wait before SIGKILL (default 10)
stdout_logfile=%(ENV_HOME)s/.services/supervisord/solr/log/default.log
stdout_logfile_maxbytes=1MB ; filesize at which to rotate logfiles (default ist 50MB)
stdout_logfile_backups=10 ; number of stdout logfile backups (0 means none, default 10)
stderr_logfile=%(ENV_HOME)s/.services/supervisord/solr/log/default.err
stderr_logfile_maxbytes=1MB ; filesize at which to rotate logfiles (default is 50MB)
stderr_logfile_backups=10 ; number of stderr logfile backups (0 means none, default 10)

For Supervisord to monitor the Solr process, Solr must be running in the foreground (option -f).

If the Solr process needs to still be running for the tests covered later in this guide, first stop this process with Ctrl+C.

Use supervisorctl update to apply the new configuration for Solr:

supervisorctl update
solr: added process group

Attention: If you receive an error, you must uniquely execute before "hpservices supervisord start".

For more detailed information on working with CSC and the options it offers, refer to the guide for Custom Service Control.

Web proxy (Nginx) on Solr administration interface

If you now want to make your application accessible via HTTP(S), you must configure your website in the Hostpoint Control Panel so that the web server will route requests to Solr via proxy.

In your Hostpoint Control Panel, create a website of the type “Nginx proxy for own application”:

Server address and port

The proxy function expects that your application will be listening to the IPv4 loopback address 127.0.0.1, meaning that you only have to enter the port: 8983.

Protecting access with a password

To protect access to your Nginx-linked website from the outside with username and password, you can create an htpasswd file as follows:

htpasswd -c ~/app/solr/.htpasswd admin

This file must be saved in the Hostpoint Control Panel under
«Websites» > «Edit website» > «Security» > «Password protection».

After the configuration has been applied successfully, you will only be able to access your website with a username and password.

Additional information

• Guide: Custom Service Control (CSC)
• Solr Overview: http://lucene.apache.org/solr/guide/7_6/a-quick-overview.html
• Solr Download: https://lucene.apache.org/solr/mirrors-solr-latest-redir.html
• Solr Tutorials: http://lucene.apache.org/solr/guide/7_6/solr-tutorial.html#solr-tutorial
• PHP Solr Examples: http://php.net/manual/de/solr.examples.php
• Reverse Proxy: https://de.wikipedia.org/wiki/Reverse_Proxy