--- /dev/null
+This document describes the installation of the Index Data Local
+Unified Index (lui-solr) on Debian Linux
+
+Prerequisites
+=============
+
+* lui-solr is based on Solr 5.x, which requires Java 7. The package
+depends on openjdk-7-jdk.
+
+Pre-installation
+================
+
+* Add the Index Data apt repository to your system. Add the following
+content to /etc/apt/sources.list.d/indexdata.list:
+
+```
+ deb http://ftp.indexdata.dk/debian jessie main restricted
+ deb-src http://ftp.indexdata.dk/debian jessie main restricted
+
+```
+
+* The 'restricted' repo requires IP authentication. Please send
+access requests to 'support@indexdata.com' if necessary.
+
+* Index Data packages are signed with a GPG key. Add the key to your
+apt keyring.
+
+```
+ wget http://ftp.indexdata.com/pub/debian/indexdata.asc -O - | sudo apt-key add -
+ sudo apt-get update
+
+```
+
+* Masterkey LUI stores its Solr indexes by default in
+/var/lib/masterkey/lui/data. Ensure this partition is large enough to
+accomodate your Solr indexes.
+
+Installation
+============
+
+The lui-solr package installs a Solr binary installation in
+/usr/share/masterkey/lui, a default configuration in
+/etc/masterkey/lui, a data directory in /var/lib/masterkey/lui/data,
+and logs in /var/log/masterkey/lui. It creates the "lui-solr" service
+and installs an init script for startup. The Solr server runs by
+default on port 8983, and processes and files are owned by the
+"lui-solr" user.
+
+* Install the masterkey-lui-solr5 package:
+
+```
+ sudo apt-get install masterkey-lui-solr5
+
+```
+
+ This will install and start up the lui-solr service with the default
+ configuration.
+
+* Increase the JVM heap size for Solr. The ideal setting
+depends on several factors, including the total amount of RAM
+available on the system and the size of your indexes. The default of
+512m, however, is likely too low for production. Edit
+/etc/masterkey/lui/lui-solr.in.sh and increase 'SOLR_HEAP'. Example:
+
+```
+ SOLR_HEAP="2048m"
+
+```
+
+ See the comments in lui-solr.in.sh for more examples of memory and
+ garbage collection fine-tuning.
+
+* Restart the lui-solr service.
+
+* Verify that Solr is running normally by connecting to the Solr Admin
+console on port 8983:
+
+```
+ curl http://localhost:8983/solr
+
+```
+
+* Solr logs are available at /var/log/masterkey/lui/solr.log.
--- /dev/null
+The lui-solr repository offers two ways for developers to run lui-solr
+out of the checked out git repository to test changes in schema and
+Solr core configuration.
+
+Installation
+============
+
+Installing in userspace on the developer's system (Linux and MacOS)
+-------------------------------------------------------------------
+
+### Prerequisites
+
+* lui-solr is a repackaging of Solr 5.x, which requires Java 7
+
+### Installation
+
+* The 'dev-install.sh' script in the root of the repository working
+ directory unpacks Solr into the working directory and links the
+ configuration files from the 'conf/' directory into the Solr
+ installation.
+
+* After running dev-install.sh, the Solr installation can be
+ controlled from the 'solr-<version>/bin/solr' script. Examples:
+
+```
+ $ solr-5.5.1/bin/solr start
+ $ solr-5.5.1/bin/solr stop
+
+```
+
+* The developer can work directly with the files in the 'conf/'
+ directory.
+
+* NOTE: do not commit the files in the 'solr-<version>/' directory to
+ the repository!
+
+Installing in a VM using VirtualBox, Vagrant, and Ansible
+---------------------------------------------------------
+
+The repository includes a Vagrantfile and an Ansible playbook
+('dev-deploy.yml') to build a VM with Debian Jessie and deploy
+lui-solr to it.
+
+### Prerequisites
+
+* VirtualBox <https://www.virtualbox.org/>
+
+* Vagrant <https://www.vagrantup.com/>
+
+* Ansible <http://www.ansible.com>,
+ <http://docs.ansible.com/ansible/intro_installation.html>
+
+### Installation
+
+* From the working directory:
+
+```
+ vagrant up
+
+```
+
+ The files in the 'conf/' directory will control the Solr
+ installation on the virtual machine.
--- /dev/null
+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>`.
projects / lui-solr.git / commitdiff