From 02e8f7338e6a20792f0a3a42f5cee82688d9c8dd Mon Sep 17 00:00:00 2001 From: Ingo Schommer Date: Wed, 18 Jul 2012 17:54:59 +0200 Subject: [PATCH] Improved docs --- docs/README.md | 36 ++++++++----------- docs/Solr.md | 96 +++++++++++++++++++++++++++++--------------------- 2 files changed, 70 insertions(+), 62 deletions(-) diff --git a/docs/README.md b/docs/README.md index 3016b90..ff51261 100644 --- a/docs/README.md +++ b/docs/README.md @@ -52,38 +52,30 @@ Basic usage is a four step process: 1). Define an index in SilverStripe (Note: The specific connector index instance - that's what defines which engine gets used) -```php -mysite/code/MyIndex.php: - -addClass('Page'); - $this->addFulltextField('DocumentContents'); + // File: mysite/code/MyIndex.php: + addClass('Page'); + $this->addFulltextField('DocumentContents'); + } } -} -``` 2). Add something to the index (Note: You can also just update an existing document in the CMS. but adding _existing_ objects to the index is connector specific) -```php -$page = new Page(array('Contents' => 'Help me. My house is on fire. This is less than optimal.')); -$page->write(); -``` + $page = new Page(array('Contents' => 'Help me. My house is on fire. This is less than optimal.')); + $page->write(); + +Note: There's usually a connector-specific "reindex" task for this. 3). Build a query -```php -$query = new SearchQuery(); -$query->search('My house is on fire'); -``` + $query = new SearchQuery(); + $query->search('My house is on fire'); 4). Apply that query to an index -```php -$results = singleton($index)->search($query); -``` + $results = singleton('MyIndex')->search($query); Note that for most connectors, changes won't be searchable until _after_ the request that triggered the change. diff --git a/docs/Solr.md b/docs/Solr.md index 03e6ccd..22dfc99 100644 --- a/docs/Solr.md +++ b/docs/Solr.md @@ -1,67 +1,83 @@ # Solr connector for SilverStripe fulltextsearch module -This module provides a fulltextsearch module connector to Solr. +## Introduction +This module provides a fulltextsearch module connector to Solr. It works with Solr in multi-core mode. It needs to be able to update Solr configuration files, and has modes for doing this by direct file access (when Solr shares a server with SilverStripe) and by WebDAV (when it's on a different server). -Since Solr is Java based, this module requires a Java runtime to be present on the server Solr is running on (not necessarily -the same physical machine the SilverStripe server is on). +See the helpful [Solr Tutorial](http://lucene.apache.org/fulltextsearch/api/doc-files/tutorial.html), for more on cores and querying. -* See the helpful [Solr Tutorial](http://lucene.apache.org/solr/api/doc-files/tutorial.html), for more on cores and querying. +## Requirements -## Getting started quickly (dev mode) +Since Solr is Java based, it requires Java 1.5 or greater installed. +It also requires a servlet container such as Tomcat, Jetty, or Resin. +Jetty is already packaged with the module. -Configure Solr in file mode +See the official [Solr installation docs](http://wiki.apache.org/solr/SolrInstall) +for more information. -```php -mysite/_config.php: +Note that these requirements are for the Solr server environment, +which doesn't have to be the same physical machine as the SilverStripe webhost. - 'localhost', - 'indexstore' => array( - 'mode' => 'file', - 'path' => BASE_PATH . '/fulltextsearch/thirdparty/solr/server/solr' - ) -)); -``` +Configure Solr in file mode. The 'path' directory has to be writeable +by the user the Solr search server is started with (see below). + + // File: mysite/_config.php: + 'localhost', + 'indexstore' => array( + 'mode' => 'file', + 'path' => BASE_PATH . '/fulltextsearch/thirdparty/fulltextsearch/server/solr' + ) + )); Create an index -```php -mysite/code/MyIndex.php: - -addClass('Page'); - $this->addAllFulltextFields(); + // File: mysite/code/MyIndex.php: + addClass('Page'); + $this->addAllFulltextFields(); + } } -} -``` -* Open a terminal, change to thirdparty/solr/server and start Solr by running `java -jar start.jar` -* In another terminal run the configure task `sake dev/tasks/Solr_configure` -* Then run the configure task `sake dev/tasks/Solr_reindex` +Start the search server (via CLI, in a separate terminal window or background process) -You can now visit http://localhost:8983/solr/MyIndex/admin/ to search the contents of the now created Solr index via the native SOLR UI + cd fulltextsearc/thirdparty/fulltextsearch/server/ + java -jar start.jar + +Initialize the configuration (via CLI) + + sake dev/tasks/Solr_configure + +Reindex + + sake dev/tasks/Solr_reindex + +## Usage + +TODO ## Debugging -It is possible to manually replicate the data automatically sent to Solr when saving/publishing in SilverStripe, -which is useful when debugging front-end queries, see: thirdparty/solr/server/silverstripe-solr-test.xml but roughly: +You can visit `http://localhost:8983/solr/MyIndex/admin/` +to search the contents of the now created Solr index via the native SOLR web interface. +Replace "MyIndex" with your own index definition as required. -``` -#> java -Durl=http://localhost:8983/solr/MyIndex/update/ -Dtype=text/xml -jar post.jar silverstripe-solr-test.xml -``` +It is possible to manually replicate the data automatically sent +to Solr when saving/publishing in SilverStripe, +which is useful when debugging front-end queries, +see `thirdparty/fulltextsearch/server/silverstripe-solr-test.xml`. ------ + java -Durl=http://localhost:8983/solr/MyIndex/update/ -Dtype=text/xml -jar post.jar silverstripe-solr-test.xml These instructions will get you running quickly, but the Solr indexes will be stored as binary files inside your SilverStripe project. You can also copy the thirdparty/solr directory somewhere else. The instructions above will still apply - just set the path value in mysite/_config.php to point to this other location, and of course run `java -jar start.jar` from the new directory, -not the thirdparty one. - +not the thirdparty one. \ No newline at end of file