[doc,search] Update docs with Solr deployment details and conventions

doc/configuration.rst

@@ -413,14 +413,16 @@ a single CKAN instance then this can be ignored.
 .. index::
    single: solr_url
 
+.. _solr_url:
+
 solr_url
 ^^^^^^^^
 
 Example::
 
  solr_url = http://solr.okfn.org:8983/solr
  
-This configures the Solr server used for search. The SOLR schema must be the one in ``ckan/config/schema.xml``.
+This configures the Solr server used for search. The SOLR schema must be one of the ones in ``ckan/config/solr`` (generally the last one).
 
 Optionally, ``solr_user`` and ``solr_password`` can also be passed along to specify HTTP Basic authentication details for all Solr requests. 
 

doc/index.rst

@@ -18,6 +18,7 @@ Contents:
    install-from-package
    install-from-source
    post-installation
+   solr-setup
    theming
    loading_data
    paster

doc/install-from-package.rst

@@ -642,12 +642,10 @@ You can now proceed to :doc:`post-installation`.
     If you don't do this and you install different versions of the same Python
     packages into the different pyenvs in ``/var/lib/ckan`` for each instance,
     there is a chance the CKAN instances might use the wrong package.
+   
+    If you want to make sure that you CKAN instances are using different Solr indexes, you can
+    configure Solr to run in multi-core mode. See :ref:`solr-multi-core` for more details.
     
-    The CKAN team have also recently had difficulties with CKAN instances writing
-    over each other's Solr search indexes. These have been documented in `ticket
-    #1430 <http://trac.ckan.org/ticket/1430>`_. If you run into the same problems
-    send an email to `ckan-dev <http://lists.okfn.org/mailman/listinfo/ckan-dev>`_.
-
 CKAN packaging is well tested and reliable with single instance CKAN installs.
 Multi-instance support is newer, and whilst we believe will work well, hasn't
 had the same degree of testing. If you hit any problems with multi-instance

doc/install-from-source.rst

@@ -250,21 +250,7 @@ Install the Source
 
 10. Setup Solr.
 
-   Edit the jetty config file (/etc/default/jetty by default on Ubuntu),
-   changing the following:
-
-   ::
-
-       NO_START=0            # (line 4)
-       JETTY_HOST=127.0.0.1  # (line 15)
-       JETTY_PORT=8983       # (line 18)
-
-   Then replace Solr's schema.xml file with a symlink to the one in the CKAN source (Note: The path ``~/pyenv/src/ckan/ckan/config/schema.xml`` will probably need to be to be adjusted for your system. Also ensure it is an absolute path.)
-
-   ::
-
-       sudo mv /usr/share/solr/conf/schema.xml /usr/share/solr/conf/schema.xml.bak
-       sudo ln -s ~/pyenv/src/ckan/ckan/config/schema.xml /usr/share/solr/conf/schema.xml
+   Set up Solr following the instructions on :ref:`solr-single` or :ref:`solr-multi-core` depending on your needs.
 
    Set appropriate values for the ``ckan.site_id`` and ``solr_url`` config variables in your CKAN config file:
 
@@ -273,25 +259,6 @@ Install the Source
        ckan.site_id=my_ckan_instance
        solr_url=http://127.0.0.1:8983/solr
 
-   You should now be able to start Solr:
-
-   ::
-
-       sudo service jetty start
-
-  .. note:: If you get the message `Could not start Jetty servlet engine because no Java Development Kit (JDK) was found.` then you will have to edit /etc/profile and add this line to the end such as this to the end (adjusting the path for your machine's jdk install)::
-
-       JAVA_HOME=/usr/lib/jvm/java-6-openjdk-amd64/
-
-    Now run::
-
-       export JAVA_HOME
-       sudo service jetty start
-
-
-  Now you should check Solr is running ok by browsing: http://localhost:8983/solr/
-
-  For more information on Solr setup and configuration, see the CKAN wiki: http://wiki.ckan.net/Solr_Search
 
 
 11. Run the CKAN webserver.