X-Git-Url: http://git.indexdata.com/?p=lui-solr.git;a=blobdiff_plain;f=doc%2Fupgrade.md;fp=doc%2Fupgrade.md;h=0a9d0f8694ddf76d35cfec037a1f7676919d092f;hp=0000000000000000000000000000000000000000;hb=d188841af6b3330fa40b3d5083209653ac85f418;hpb=357b6cb94c8ea913eff88ae89d21a70a51d76428

diff --git a/doc/upgrade.md b/doc/upgrade.md
new file mode 100644
index 0000000..0a9d0f8
--- /dev/null
+++ b/doc/upgrade.md
@@ -0,0 +1,106 @@
+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>`.