From: Wayne Schneider Date: Mon, 18 Jul 2016 16:20:25 +0000 (-0500) Subject: Documentation updates. X-Git-Tag: v0.10~2 X-Git-Url: http://git.indexdata.com/?p=lui-solr.git;a=commitdiff_plain;h=d188841af6b3330fa40b3d5083209653ac85f418;hp=357b6cb94c8ea913eff88ae89d21a70a51d76428 Documentation updates. --- diff --git a/Changes b/Changes index ebbe0f3..65392ae 100644 --- a/Changes +++ b/Changes @@ -1,6 +1,7 @@ 0.10 [IN PROGRESS] - Documentation updates - Clean up unused files + - Update schema/solrconfig to prevent indexing of *_binary fields - schema/solrconfig updates for Solr 5 - Includes Solr 5.5.1 - Remove RHEL packaging diff --git a/debian/install b/debian/install index 578ecf9..2723a16 100644 --- a/debian/install +++ b/debian/install @@ -1,2 +1,3 @@ dist usr/share/masterkey/lui conf/* etc/masterkey/lui +doc/* usr/share/doc/masterkey-lui-solr5 diff --git a/doc/apache-solr-ref-guide-5.5.pdf b/doc/apache-solr-ref-guide-5.5.pdf new file mode 100644 index 0000000..101a82a Binary files /dev/null and b/doc/apache-solr-ref-guide-5.5.pdf differ diff --git a/doc/debian-install.md b/doc/debian-install.md new file mode 100644 index 0000000..4848314 --- /dev/null +++ b/doc/debian-install.md @@ -0,0 +1,83 @@ +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. diff --git a/doc/dev-install.md b/doc/dev-install.md new file mode 100644 index 0000000..2d3d481 --- /dev/null +++ b/doc/dev-install.md @@ -0,0 +1,63 @@ +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-/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-/' 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 + +* Vagrant + +* Ansible , + + +### Installation + +* From the working directory: + +``` + vagrant up + +``` + + The files in the 'conf/' directory will control the Solr + installation on the virtual machine. 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/. + +* 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//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 + (). + +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//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 ``. diff --git a/docs/apache-solr-ref-guide-5.5.pdf b/docs/apache-solr-ref-guide-5.5.pdf deleted file mode 100644 index 101a82a..0000000 Binary files a/docs/apache-solr-ref-guide-5.5.pdf and /dev/null differ