Beschreibung
===================

Infopark SES ist ein Ruby-Gem, das zum Zweck der Indizierung von Infopark CMS Fiona-Inhalten
vom CM Nachrichten über geänderte CMS-Objekte entgegen nimmt, Indizierungs-
oder Deindizierungs-Anfragen erzeugt und diese an Solr sendet.

Das Infopark SES Ruby-Gem ergänzt eine bestehende Rails-App, typischerweise die
Website-App eines konkreten Projekts. Die Rails-App muss bereits den Infopark
Rails Connector einsetzen. Infopark SES setzt eine Rails Connector-Anbindung
zur CMS-Datenbank voraus.

Infopark SES besteht aus dem SES Indexer-Resque-Worker, einem Installer für
Apache Solr und der Logik zum Verdrahten dieser Software-Komponenten. Der
eigentliche Kern des Infopark SES ist der Indexer. Er fragt unter Benutzung des
Rails Connectors Objekt-Felder ab, und schickt diese aufbereitet an Apache
Solr.

Der Installer für Redis (ist Voraussetzung für Resque) ist nicht enthalten.
Die Installation ist auf http://redis.io/download beschrieben. Empfehlung: von
einem Sysadmin mit einem Paketmanager installieren lassen (z.B. emerge),
Eintragen in den Default-Runlevel (z.B. rc-update add redis default) und
starten mit /etc/init.d/redis start.

Lizenz
========

Das Gem steht unter LGPL v3. Details siehe LICENSE.md.

Gem testen
==============

Es wird eine Fiona-6.7-Entwicklungsumgebung per Vagrant in ~/nps vorausgesetzt, die auch
bereits gebaut sein muss:

  git clone -b 6.8-maint git@github.com:infopark/fiona.git
  cd fiona
    git submodule update --init --recursive

  vagrant ssh
    cd nps
    ln -s ~/licenses/infopark-internal-restricted-license.xml config/license.xml
    rake build


Die Tests des Infopark SES Gems werden mit

  vagrant ssh
    cd ~/ses
    mysqladmin -uroot create test_ses_lucene
    bundle
    bundle exec rake test

ausgeführt. Die Tests sind vollständige Integrationstests. Sie liegen in
test_app. Die von der test_app verwendeten Gems liegen in vendor/cache.

Verwendet wird Ruby 1.9.



Gem bauen
==============

  rake build



Installation
==============

Einbindung des Infopark SES Gem in die Rails-App
------------------------------------------------

Gemfile:

  gem "infopark_ses"

Infopark SES neben den Infopark Rails Connector und die anderen Gems in vendor/cache ablegen:

  cp infopark_ses-x.y.z.gem vendor/cache/

Gems installieren:

  bundle

Bundler lädt notwendige Gems bei Bedarf von rubygems.org herunter. Alle
Gem-Dateien werden, bevor sie installiert werden, automatisch in vendor/cache
abgelegt, wenn mindestens ein Gem dort liegt. Bundler hält diesen Cache
selbständig up-to-date. Alle Gems in vendor/cache können eingecheckt werden.
Das wird sogar empfohlen, weil so das Deployment (mit Capistrano und Bundler)
auch ohne Internet-Verbindung ausgeführt werden kann.

Infopark SES bringt beispielhaft Konfigurationsdateien mit, die in der
Projekt-Rails-App benötigt werden:

  rails g ses:install

Ein paar dieser generierten Dateien werden im Folgende beschrieben:

In config/initializers/indexer.rb wird festgelegt, welche Attribute eines Obj
unter welchem Key im Solr-Index gespeichert werden sollen.
Infopark::SES::Indexer.index_fields liefert für ein Obj einen Hash mit der
Abbildung von Index-Keys auf Obj-Attribut-Werte. Liefert die Konfiguration nil,
wird die Datei nicht indiziert bzw. deindiziert.
Infopark::SES::Indexer.index_fields soll projektspezifisch konfiguriert werden.

config/initializers/filter.rb enthält Konfigurationseinstellungen, um den
Fiona-IF-Filter (.doc -> .html usw.) einzubinden.


Die Änderungen am Projekt können jetzt eingecheckt werden.




Deployment in die Preview-Umgebung konfigurieren
--------------------------------------------------

Die Capistrano-Konfiguration für das Deployment mit Bundler kann folgendermaßen
ergänzt werden. Am Anfang der Datei config/deploy.rb einfügen:

  set :bundle_flags, "--deployment --quiet --local"
  require 'bundler/capistrano'

In den Namespace :deploy zusätzlich den Task :restart_ses_indexer einfügen:

  task :restart_ses_indexer, :roles => :app do
    if stage == 'cms_preview'
      run "cd #{current_path} && bundle exec rake index:worker:restart"
    end
  end

Und weiter unten:
  after "deploy:restart", "deploy:restart_ses_indexer"



Beim Deployment installiert Bundler mit der o.g. Option --deployment die Gems
automatisch ins Capistrano-Projekt-Verzeichnis shared/bundle, also direkt neben
releases, current usw. Damit werden Gems im User-Space projektbezogen verwaltet.

Deploy ins Preview-Environment:

  cap deploy



Anbindung von Resque auf dem CMS-Server
------------------------------------------------------------------------

Bei Änderungen an Objekten werden vom CM entsprechende Indizierungs-Jobs in die
Job-Queue von Resque gestellt werden. In Fiona existiert bereits die
Schnittstelle, um die Tcl-Prozedur objectChangedCallback aufzurufen. Diese
Prozedur muss nur noch im CM implementiert werden. Die Beispiel-Implementierung
wird folgermaßen ins CM-Script-Verzeichnis kopiert und anschließend
konfiguriert:

  cp $(bundle show infopark_ses)/cms-callback/* ~/CMS-Fiona/instance/default/script/cm/serverCmds/
  gem install resque --no-ri --no-rdoc --no-user-install --install-dir ~/CMS-Fiona/instance/default/script/gems
  gem install json --no-ri --no-rdoc --no-user-install --install-dir ~/CMS-Fiona/instance/default/script/gems

Schließlich muss noch der CM neu gestartet werden, damit er den neuen Callback nutzt:

  ~/CMS-Fiona/instance/default/bin/rc.npsd restart CM




Installation von Solr
------------------------------------

(Homepage: <http://lucene.apache.org/solr/>)

Der Java-Server Apache Solr wird ebenfalls mit curl heruntergeladen und in $HOME
installiert. Per Konvention zeigt ein Symlink namens apache-solr auf das
ausgepackte Verzeichnis, damit es einfach über ~/apache-solr referenziert
werden kann. Anschließend wird die neue Installation so konfiguriert, dass sie
für den Einsatz mit Fiona geeignet ist:

  ssh cms-host
  cd $project/preview/current
  bundle exec ses-apache-solr install

Starten:

  bundle exec ses-apache-solr start

Stoppen:

  bundle exec ses-apache-solr stop

Status:

  bundle exec ses-apache-solr status


Zur Problemanalyse ist der Apache Solr erreichbar unter:
http://localhost:8983/solr/admin bzw. http://localhost:8983/solr/de/admin bei
Verwendung von mehreren Cores (aka. Collections). Im letzteren Fall ist der
URL-Bestandteil "de" der Name des Cores.



Komplette Indizierung
---------------------------

  ssh cms-host
  cd $project/preview/current
  RAILS_ENV=production bundle exec rake index:worker:start
  RAILS_ENV=production bundle exec rake index:all



Integration der Suche in Rails
--------------------------------

Die Rails-Connector-Add-Ons ab Version 6.7.3 unterstützen den Lucene-basierten SES.

Zur Aktivierung muss der SearchRequest umdefiniert werden (lib/search_request.rb):

  class SearchRequest < RailsConnector::LuceneSearchRequest
  end

Das Interface bleibt gleich, bis auf folgende Ausnahmen: Querys werden in Solr
Query Language anstatt VQL geschrieben. Die möglichen Optionen sind im
LuceneSearchRequest dokumentiert.