Permalink
Browse files

improving readme and adding license

  • Loading branch information...
1 parent f36792e commit dfc155bb9815e43513538dd28370b35eecb187ba @ryanb committed Aug 27, 2010
Showing with 48 additions and 30 deletions.
  1. +20 −0 LICENSE
  2. +28 −30 README.rdoc
View
20 LICENSE
@@ -0,0 +1,20 @@
+Copyright (c) 2010 Ryan Bates
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
View
58 README.rdoc
@@ -1,62 +1,60 @@
= Xapit Server
-IMPORTANT: This project is currently vaporware.
+A central Rack application to interact with a Xapian database. This way your data stays in sync without needing to update the readable databases on each instance.
-For an alternative solution see Xapit Sync.
+This is intended to be used through the {Xapit gem}[http://github.com/ryanb/xapit/tree/master].
-http://github.com/ryanb/xapit-sync/tree/master
+== Pros & Cons
-== Xapit
+Compared to {Xapit Sync}[http://github.com/ryanb/xapit-sync/tree/master]
-Xapit is a Ruby library for interacting with Xapian, a full-text search engine.
-
-http://github.com/ryanb/xapit/tree/master
-
-
-== How it Works
-
-Xapit Server provides a Rack application which hosts a writable Xapian database and allows interaction through a REST API. Xapit will use this remote database for all search queries and record updates.
-
-There are several advantages to this solution.
+=== Pros
* all records will be updated instantly so you do not have to worry about syncing the database.
-* the database is only loaded into memory once, not separately for each Rails process. This is very important if you have a large database.
-* allows the Xapian database to be stored on a separate machine than the application.
-* completely independent of Rails, so you can use it with other Ruby applications.
+* the database is only loaded into memory once, not separately for each Rails instance. This is very important if you have a large database.
+* allows the Xapian database to be stored on a separate machine or network than the application.
+* does not require Rails.
-Here are some disadvantages when compared to Xapit Sync.
+=== Cons
* additional security issues (if Rack server is exposed).
* requires a separate daemon process to constantly be running (and monitored).
* more overall traffic to/from the external process.
-* greater overhead to perform search requests.
* more difficult to test in staging/development.
== Setup
-To use this plugin you simply have to setup a rack server. If you are using Phusion Passenger it may look like this.
+To use Xapit Server you will need to set up a Rackup file like this.
- <VirtualHost *:80>
- ServerName xapit-server.example.com
- DocumentRoot /path/to/xapit-server/public
- </VirtualHost>
+ # config.ru
+ require "xapit_server"
+ run XapitServer::Application.new(:database_path => "/path/to/xapiandb")
+There are a number of webservers which can host this Rack application: Phusion Passenger, Mongrel, Thin, Unicorn, etc. I'll leave it up to you to set that up.
-Then configure Xapit to use this server by passing the URL to the database path.
+Once it is running, just change the Xapit database path to point to the URL of the Xapit Server.
# in config/initializers/setup_xapit.rb
- Xapit::Config.setup(:database_path => "http://xapit-server.example.com")
+ Xapit::Config.setup(:database_path => "http://locahost:12345")
+There is no authorization performed by Xapit Server, so be certain to restrict the port it is running on.
+
+
+== Initial Data
+
+If you already have a large set of data which needs to be indexed, running that all through Xapit Server will create a lot of overhead. Instead I recommend having Xapit go straight to the file system to populate the initial database.
+
+ # in config/initializers/setup_xapit.rb
+ Xapit::Config.setup(:database_path => "/path/to/xapiandb")
-== Implementation
+Once this is done, use that database through Xapit Server.
-This solution requires a more complex implementation than Xapit Sync. Not all Xapian classes are easily serialized. This may require Xapit to take extra steps to minimize the amount of traffic to the REST API.
-=== Commands
+== Commands
-Here are some ideas on how the REST api will work.
+Xapit Server is a REST API, here are the commands which it responds to.
==== POST /documents

0 comments on commit dfc155b

Please sign in to comment.