+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>`.