Revision as of 03:00, 28 June 2013

There are two forms of search on Dreamwidth installations: both are optional and require further setup.

User search searches for users matching certain characteristics. Sphinx searches through entries, comments, and more recently, support requests.

User Search

Not heavily documented, instructions for setup can be found in Set_up_UserSearch.

Sphinx

Search is available on the search page. There are two modes of search: site search, and per-journal search.

Site search only shows public content. Journal search may contain locked content, following the regular behavior for whether you can see the locked content or not. That is, if you can see it on the journal, then you can find it with search. If you can't see it on the journal, then you won't see it in the search results. There's also an option to search by comments. Only comments made on paid users' journals are indexed for technical reasons (site load).

Setup

This page documents the process you will need to go through to setup the Sphinx search system that Dreamwidth uses. This is not an easy process, and the documentation is probably going to need some iterations to get to a very useful state.

I only suggest setting up the search system if you have a good amount of time to mess around with things. If you need some help, feel free to grab me (<dw-user>mark</dw-user>) anytime and I'll help out.

Software Installation

First, you will need to setup the Sphinx software. Very first, you should make sure you have some packages (Ubuntu Intrepid):

apt-get install libpath-class-perl libmysqlclient15-dev g++

The instructions are different depending on your version of Ubuntu, so choose the appropriate version:

Jaunty/9.04 and older

Installing File::SearchPath and Sphinx::Search

There are two Perl packages that you will have to download:

http://search.cpan.org/CPAN/authors/id/T/TJ/TJENNESS/File-SearchPath-0.05.tar.gz
http://search.cpan.org/CPAN/authors/id/J/JJ/JJSCHUTZ/Sphinx-Search-0.12.tar.gz

Now, you need to build these. They are standard Perl packages which you can build with dh-make-perl. Do File::SearchPath first (and then install it) and then you can build Sphinx::Search (and install it).

Installing the Sphinx package

You will need to download the Sphinx package:

http://sphinxsearch.com/downloads/sphinx-0.9.8.1.tar.gz

The Sphinx package itself is a standard project style. Setup and installation looks something like this:

tar -zxvf sphinx-0.9.8.1.tar.gz
cd sphinx-0.9.8.1/
./configure
make
make install

Karmic/9.10 and newer

Installing File::SearchPath and Sphinx::Search

From Ubuntu 9.10 and up, these Perl packages are available in the packaging system. You can install them in one step:

apt-get install libfile-searchpath-perl libsphinx-search-perl

Installing the Sphinx package

You will need to download the Sphinx package:

http://sphinxsearch.com/downloads/sphinx-0.9.9.tar.gz

The Sphinx package itself is a standard project style. Setup and installation looks something like this:

tar -zxvf sphinx-0.9.9.tar.gz
cd sphinx-0.9.9/
./configure
make
make install

It is important that you match up the versions of the Perl packages and the Sphinx package; otherwise, your searches will silently fail due to incompatibilities in the API. (For instance, assuming the proper workers are running, if "search -q terms" returns results, while a site search always fails, this is one possible reason.)

Assuming that all works, you should have everything installed that you need to get the search system setup. Moving on!

Configuration

There are several points to configure. Let's start with the configuration of your database.

Database

You will need to create a new database. Something like this process will work:

CREATE DATABASE dw_sphinx;
GRANT ALL ON dw_sphinx.* TO dw@'localhost' IDENTIFIED BY 'dw';
USE dw_sphinx;

Now, you have to make a table. Use these CREATE TABLE statements:

The table is a pretty straightforward table. It just stores the posts, who they're by, where they're at, and some basic security information. Note that this table has the full uncompressed subject and text of the entries, so it can get rather large.

Site

Configuring your site is next. This involves adding a new section to your %DBINFO hash, like this:

sphinx => {
    host => '127.0.0.1',
    port => 3306,
    user => 'dw',
    pass => 'dw',
    dbname => 'dw_sphinx',
    role => {
        sphinx_search => 1,
    },
},

You also need to add a configuration elsewhere in the file that tells your system where the search daemon will be. Port 3312 is the default:

# sphinx search daemon
@SPHINX_SEARCHD = ( '127.0.0.1', 3312 );

That's it for site configuration. Once you have the above two options in, then your site will do all the right things to make the search active. Of course, we still have to configure Sphinx itself...

Sphinx

Left this to last as it's probably the trickiest. The first step is, assuming you're going to be running Sphinx as root (I do), to make the directory it needs:

mkdir /var/data

Now, we need to set up the configuration file. By default, sphinx looks for the file /usr/local/etc/sphinx.conf. If that's not present on your system, try running "indexer --quiet"; it will fail if it didn't find a config file, but will helpfully tell you where it tried to look.

That's right. It's long. But it's actually almost identical to the configuration file that comes with Sphinx. I had to do a lot of tweaking to figure out the right combination of values for UTF-8 support and the like, but the rest is pretty straightforward.

Make sure to customize `sql_user` and `sql_pass` in the configuration files to match what you used earlier.

Testing

To make sure that your test setup is working, once you have all of the configuration done, try to run the indexer (as root).

indexer --all

You should see it spit out some stuff saying it's collecting documents, and if all goes well, you should see files in /var/data. You won't be able to search yet because you haven't placed any data in your search database, but you'll at least have confirmed that you have Sphinx configured properly.

Search Architecture

Making content searchable requires two things:

• a search database. The search database contains the text of entries and comments that we want to be searchable. It's separate from the main database. Every time an entry or comment is posted or edited, it needs to be copied from the main database into the search database. The worker that does this is sphinx-copier, which is run by TheSchwartz.
• a search index. Doing a search on raw text is painfully slow, so Sphinx processes the contents of the search database further -- it creates an index of words, then runs searches against that index instead of the raw text itself. Processing the text this way also makes it possible for a search for "test" to turn up "tests", "testing", etc. The index is created by running a program named, surprisingly enough, indexer.

Running searches and getting results requires two more:

• the Sphinx search daemon -- the program that actually runs searches. This is searchd.
• a search worker, which connects to the Sphinx daemon, feeds it queries, and retrieves the results. This is sphinx-search-gm, a Gearman job.

Assembling the pieces (test env)

Now, here's how we put all of those pieces together in a test environment.

• First, we need to have both TheSchwartz and Gearman set up and working -- sphinx-copier depends on the former, and sphinx-search-gm on the latter.
• Now, we want to run both of those workers in the foreground so that we can keep an eye on them. In separate terminal sessions, run

bin/worker/sphinx-copier -v
bin/worker/sphinx-search-gm -v

• Next, we need to have the search daemon running -- also in the foreground:

searchd --console

• To get data into the search db, you have two options:
  • You can post to some of your paid accounts. Now that sphinx-copier is running, it will pick up anything new that you post and schedule it for addition to the search db.
  • Alternatively, you can run the manual copier, which will tell sphinx-copier about any posts or comments that area already on your site:

bin/schedule-copier-jobs

• ...running that will get your sphinx-copier busy copying data into the dw_sphinx database you made earlier. You can see if it works by watching the output of the sphinx-copier -- it should say something about inserting posts. You can then go to the dw_sphinx database and select from posts_raw to see the data is actually in the system.
• Now that we have data in the search database, we have to index it. On a production site, you'd want to run the indexer every 15 minutes or so; in test, you can just run it before you do a search, if you've added new content since the last run.

  indexer --all --rotate

• Finally, restart searchd.

You should now be able to search for things from the command line or from your site! To search from the command line, use:

search -q some words

Sphinx is resource-intensive. It's intentionally been made a separate system from the main Dreamwidth site, so that it can be run on a different machine from the webservers in production.

You don't have to worry too much about load on a development server where you have little data to index and it's only you on the machine. Still, it may make sense to only turn on the search workers when you're testing something search-related.