doc/upgrade.md

   1 The masterkey-lui-solr5/masterkey-lui-solr6 packages contain a number
   2 of changes from the masterkey-lui-solr4 family of packages. The good
   3 news is that **indexes created with masterkey-lui-solr4 are compatible
   4 with masterkey-lui-solr5**.
   5
   6 That said, the move to Solr 5/6 requires significant changes to
   7 schema.xml and to solrconfig.xml, so older versions of those files are
   8 not compatible. Any customizations will need to be backported into
   9 those files. Also, because of the schema and solrconfig
  10 incompatibilities, Solr 4- and Solr 5/6-based installations cannot be
  11 in a replication relationship together (master-slave pairs must be all
  12 Solr 4 or all Solr 5/6).
  13
  14 Major Changes
  15 =============
  16
  17 * masterkey-lui-solr5/masterkey-lui-solr6 are based on Solr 5/6, which
  18   do not require a separate Java servlet container. That simplifies
  19   packaging and installation significantly, as there is no longer any
  20   need for Tomcat integration. There is only one package to install,
  21   masterkey-lui-solr5 or masterkey-lui-solr6.
  22
  23 * masterkey-lui-solr5/masterkey-lui-solr6 are installed as a separate
  24   service, since they no longer runs under Tomcat. The service name is
  25   "lui-solr", and files and processes are owned by the "lui-solr" user
  26   (created as part of the package installation).
  27
  28 * The default port for masterkey-lui-solr5/masterkey-lui-solr6 is the
  29   same as the Solr default port, 8983, to prevent conflicts when
  30   upgrading a lui-solr installation that is on the same system as a
  31   MasterKey Harvester installation (which runs by default under Tomcat
  32   on port 8080). This may require changes to Harvester datasource
  33   settings and/or search target settings for existing
  34   installations. The Solr port can be set by the user in the
  35   configuration file /etc/masterkey/lui/solr/lui-solr.in.sh (look for
  36   the SOLR_PORT variable).
  37
  38 * Solr 5/6 no longer have the feature of serving up a default core
  39   ("collection1") on the root of the web application. The
  40   masterkey-lui-solr packages install a default core named "lui",
  41   addressable at http://localhost:8983/solr/lui. This may also require
  42   changes to Harvester and search target settings.
  43
  44   * Cores are defined in the /etc/masterkey/lui/solr/solr-home
  45     directory. Indexes are stored by default in
  46     /var/lib/masterkey/lui/solr/<core-name>.
  47
  48 * There are no longer separate packages for master and slave
  49   configurations. To configure a lui-solr core as a slave, edit the
  50   configuration file
  51   /etc/masterkey/lui/solr/solr-home/<core-name>/conf/solrconfig.xml. Look
  52   for the "/replication" requestHandler.
  53
  54 * SolrCloud support (which was mostly aspirational, to be honest) is
  55   no longer available as a separate package.
  56
  57 * Package layout has changed somewhat, to better conform with the
  58   Linux FSH and with other applications in the MasterKey Platform:
  59
  60   * All configuration files are now found in /etc/masterkey/lui/solr. Core
  61     configuration (schema and solrconfig) are in
  62     /etc/masterkey/lui/solr/solr-home. Solr environment and logging are
  63     controlled by /etc/masterkey/lui/solr/lui-solr.in.sh and
  64     /etc/masterkey/lui/solr/log4j.properties, respectively.
  65
  66   * /usr/share/masterkey/lui contains only the runtime files for Solr.
  67
  68   * Data files for Solr cores are in /var/lib/masterkey/lui/solr.
  69
  70   * Logs for lui-solr are in /var/log/masterkey/lui.
  71
  72 Upgrading an existing lui-solr installation
  73 ===========================================
  74
  75 1. (Recommended) Back up the existing Solr index using the Solr backup
  76    API
  77    (<https://cwiki.apache.org/confluence/display/solr/Making+and+Restoring+Backups>).
  78
  79 2. Shut down the Solr web application on the Tomcat server. Remove the
  80    link to the deployment context fragment from
  81    /etc/tomcat<6|8>/Catalina/localhost/.
  82
  83 3. Back up any customizations made to files in the
  84    /usr/share/masterkey/lui/solr4/<master|slave>/conf/
  85    directory. These will need to be backported into the configuration
  86    for the Solr 5 core (installed in
  87    /etc/masterkey/lui/solr/solr-home/lui/conf/ by the masterkey-lui-solr5
  88    package).
  89
  90 4. Remove any masterkey-lui-solr4* packages installed on the
  91    system. This may include masterkey-lui-solr4-common,
  92    masterkey-lui-solr4-master, masterkey-lui-solr4-slave,
  93    masterkey-lui-solr4-zookeeper, masterkey-lui-solr4-common-tomcat6,
  94    masterkey-lui-solr4-master-tomcat6,
  95    masterkey-lui-solr4-slave-tomcat6,
  96    masterkey-lui-solr4-common-tomcat8,
  97    masterkey-lui-solr4-master-tomcat8, and
  98    masterkey-lui-solr4-slave-tomcat8
  99
 100 5. Install the masterkey-lui-solr5 or the masterkey-lui-solr6 package
 101    using the instructions in debian-install.md.
 102
 103 6. Make any updates necessary to the configuration files in
 104    /etc/masterkey/lui/solr and restart the lui-solr service. You should be
 105    able to point to your existing index by editing
 106    /etc/masterkey/lui/solr/solr-home/lui/solrconfig.xml and altering the
 107    entry for `<dataDir>`.
 108