The masterkey-lui-solr5 package contains a number of changes from the
masterkey-lui-solr4 family of packages. The good news is that
**indexes created with masterkey-lui-solr4 are compatible with
masterkey-lui-solr5**.

That said, the move to Solr 5 requires significant changes to
schema.xml and to solrconfig.xml, so older versions of those files are
not compatible. Any customizations will need to be backported into
those files. Also, because of the schema and solrconfig
incompatibilities, Solr 4- and Solr 5-based installations cannot be in
a replication relationship together (master-slave pairs must be all
Solr 4 or all Solr 5).

Major Changes
=============

* masterkey-lui-solr5 is based on Solr 5, which does not require a
  separate Java servlet container. That simplifies packaging and
  installation significantly, as there is no longer any need for
  Tomcat integration. There is only one package to install,
  masterkey-lui-solr5.

* masterkey-lui-solr5 is installed as a separate service, since it no
  longer runs under Tomcat. The service name is "lui-solr", and files
  and processes are owned by the "lui-solr" user (created as part of
  the package installation).

* The default port for masterkey-lui-solr5 is the same as the Solr 5
  default port, 8983, to prevent conflicts when upgrading a lui-solr
  installation that is on the same system as a MasterKey Harvester
  installation (which runs by default under Tomcat on port 8080). This
  may require changes to Harvester datasource settings and/or search
  target settings for existing installations. The Solr port can be set
  by the user in the configuration file
  /etc/masterkey/lui/lui-solr.in.sh (look for the SOLR_PORT variable).

* Solr 5 no longer has the feature of serving up a default core
  ("collection1") on the root of the web
  application. The masterkey-lui-solr5 installs a default core named
  "lui", addressable at http://localhost:8983/solr/lui. This may also
  require changes to Harvester and search target settings.

  * Cores are defined in the /etc/masterkey/lui/solr-home
    directory. Indexes are stored by default in
    /var/lib/masterkey/lui/data/<core-name>.

* There are no longer separate packages for master and slave
  configurations. To configure a lui-solr core as a slave, edit the
  configuration file
  /etc/masterkey/lui/solr-home/<core-name>/conf/solrconfig.xml. Look
  for the "/replication" requestHandler.

* SolrCloud support (which was mostly aspirational, to be honest) is
  no longer available as a separate package.

* Package layout has changed somewhat, to better conform with the
  Linux FSH and with other applications in the MasterKey Platform:

  * All configuration files are now found in /etc/masterkey/lui. Core
    configuration (schema and solrconfig) are in
    /etc/masterkey/lui/solr-home. Solr environment and logging are
    controlled by /etc/masterkey/lui/lui-solr.in.sh and
    /etc/masterkey/lui/log4j.properties, respectively.

  * /usr/share/masterkey/lui contains only the runtime files for Solr.

  * Data files for Solr cores are in /var/lib/masterkey/lui/data.

  * Logs for lui-solr are in /var/log/masterkey/lui.

Upgrading an existing lui-solr installation
===========================================

1. (Recommended) Back up the existing Solr index using the Solr backup
   API
   (<https://cwiki.apache.org/confluence/display/solr/Making+and+Restoring+Backups>).

2. Shut down the Solr web application on the Tomcat server. Remove the
   link to the deployment context fragment from
   /etc/tomcat<6|8>/Catalina/localhost/.

3. Back up any customizations made to files in the
   /usr/share/masterkey/lui/solr4/<master|slave>/conf/
   directory. These will need to be backported into the configuration
   for the Solr 5 core (installed in
   /etc/masterkey/lui/solr-home/lui/conf/ by the masterkey-lui-solr5
   package).

4. Remove any masterkey-lui-solr4* packages installed on the
   system. This may include masterkey-lui-solr4-common,
   masterkey-lui-solr4-master, masterkey-lui-solr4-slave,
   masterkey-lui-solr4-zookeeper, masterkey-lui-solr4-common-tomcat6,
   masterkey-lui-solr4-master-tomcat6,
   masterkey-lui-solr4-slave-tomcat6,
   masterkey-lui-solr4-common-tomcat8,
   masterkey-lui-solr4-master-tomcat8, and
   masterkey-lui-solr4-slave-tomcat8

5. Install the masterkey-lui-solr5 package using the instructions in
   debian-install.md.

6. Make any updates necessary to the configuration files in
   /etc/masterkey/lui and restart the lui-solr service. You should be
   able to point to your existing index by editing
   /etc/masterkey/lui/solr-home/lui/solrconfig.xml and altering the
   entry for `<dataDir>`.