doc/upgrade.md

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