Solr for WCM
                                            ============

Before installing WCM using its graphical installation program, you must first:

1- Determine which type of Solr installation you want to use with WCM.

   - Embedded or external?

   - Multicore or single-core?

2- Get the appropriate Solr installation package.

3- Install and configure Solr for use with WCM.

Embedded vs. External Solr Installation
=======================================

Embedded Solr Installation
--------------------------

An embedded Solr installation is recommended for normal WCM use. The appropriate installation
packages are available on the Nstein intranet as ZIP archives ("solr4wcm.zip" and
"solr4wcm-multicore.zip").

See the next section "Multicore vs. Single-core Solr Installation" for installation and
configuration instructions.

External Solr Installation
--------------------------

You can opt to use an external Solr installation if, for example:

- You already have a working multicore Solr installation and you want to use it with WCM.

- You need to handle a heavier-than-normal load, which requires a more scalable Web applications
  container than Jetty, such as Tomcat.

- You know what you're doing and just want to use a custom Solr installation.

In this case, see the Apache Solr documentation for installation and configuration
instructions.

However, in order to use your external Solr installations with WCM, you must first migrate the
appropriate WCM configuration files under the "solr4wcm/solr/conf" (single-core installation) or
"solr4wcm/solr/wcm/conf" (multicore installation) directory (notably "schema.xml" and
"solrconfig.xml") to your external Solr installation.

Multicore vs. Single-core Solr Installation
===========================================

By default, the WCM installation program assumes that you are using an embedded multicore Solr
installation accessible with the URI "http://localhost:8983/solr/wcm".

Note that the following sections assume an embedded Solr installation. If you want to use an
external Solr installation, you're essentially on your own, but see the previous section "External
Solr Installation".

Multicore Solr Installation
---------------------------

To use an embedded multicore Solr installation, simply unzip the "solr4wcm-multicore.zip" package
from within the "includes" directory of the WCM root directory.

In this case, Solr will be accessible with the URI "http://localhost:8983/solr/wcm" and will use the
following particular files and directories:

  solr4wcm/solr/solr.xml  (multicore configuration file)
  solr4wcm/solr/wcm/bin   ("wcm" core scripts)
  solr4wcm/solr/wcm/conf  ("wcm" core configuration files)
  solr4wcm/solr/wcm/data  ("wcm" core data files)

Note that the "wcm" comppnent of the Solr URI and the above directory names identifies the "wcm"
core as defined in the file "solr4wcm/solr/solr.xml".

To create a new core, say "wcm2", for use with another WCM installation, simply:

1- Add a new entry in the file "solr4wcm/solr/solr.xml":

   <solr persistent="false">
      <cores adminPath="/admin/cores">
         <core name="wcm" instanceDir="wcm" />
         <core name="wcm2" instanceDir="wcm2" /> <!-- NEW ENTRY -->
      </cores>
   </solr>

2- Create a new directory named "wcm2" alongside the existing "wcm" directory, being careful to use
   the right file permissions (e.g., under Apache/Linux, user = "root", group = "www-data").

3- Copy the contents of the "__CORETEMPLATE__" directory into the new directory.

4- Replace all instances of the string "__CORETEMPLATE__" in the files under the new directory's
   "conf" directory with the name of the new core ("wcm2" in our example).

   Note that the core name may be different from the directory name, depending on the <core> entry
   in the file "solr4wcm/solr/solr.xml". For example, the following entry is valid:

      <core name="SuperDuperWcm" instanceDir="wcm_super_duper" />

   The corresponding Solr URI would be:

      http://localhost:8983/solr/SuperDuperWcm

Finally, when using a single multicore Solr installation for two or more WCM installations, it's
possible to move (or symlink) the Solr installations directory (i.e., "includes/solr4wcm") anywhere
desired since the only access to Solr from WCM is via HTTP.

Single-core Solr Installation
-----------------------------

To use a single-core Solr installation, simply:

1- Unzip the "solr4wcm.zip" package from within the "includes" directory of the WCM root directory.

2- Remove or rename the file "solr4wcm/solr/solr.xml" to prevemt Solr from using multicore mode.

In this case, Solr will be accessible with the URI "http://localhost:8983/solr" and will use the
following files and directories:

  solr4wcm/solr/bin   (utility scripts)
  solr4wcm/solr/conf  (configuration files)
  solr4wcm/solr/data  (data files)

Note that in this case, there is no concept of a "core", neither in the Solr URI nor in the
directory names.