README

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 Verbinden 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-7-Installation per Vagrant in ~/nps vorausgesetzt.

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


Vorraussetzungen 
=================

Solr 6 Setz Java 8 vorraus und wird nicht unter Java 7 laufen.
Ein Betrieb mit einer ältern Solr Version ist allerdings auch möglich (zb. 5.5.2 )

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, .pdf -> .html) oder den Solr Content Extraction Library 
(Solr Cell) (.pdf, .html -> .txt) einzubinden.

Um den Indexing-Worker sauber zu überwachen wird für diesen eine pid-Dateie erzeugt,
welche die Prozess-Id des Workers enthält. Diese wird unter dem folgenden Pfad erzeugt.
Bitte stellen Sie sicher, dass der Pfad entsprechend existiert:

`YOUR_RAILS_APPLICATION/tmp/pids`

Des Worker selbst können Sie anschließend über Rake-Tasks starten und oder stoppen:

rake index:all                          # Re-index all objects
rake index:worker:restart               # Restart the worker
rake index:worker:start                 # Start the worker
rake index:worker:status                # Reports the status of the worker
rake index:worker:stop                  # Stop the worker

Der Worker erzeugt ein eigenes Log im Applikations-Log-Ordner:

`YOUR_RAILS_APPLICATION/log/resque_worker_index_COLLECTION.log`

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
	```

Das Gem stellt zwei Implementationen bereit, von denen immer nur eine aktiv sein sollte.

1. `rails_objectChangedCallback.tcl`

	Diese implementation basiert auf einem Rails-Callback. Grundlegend ruft es ein Ruby-Skript auf, um die geänderten
	Objekte in die Resque-Warteschlange zu schieben.
	Vorteil:  Funktioniert ohne weitere Abhängigkeiten
	Nachteil: Das aufrufen, des Ruby-Script ist eventuell langsam ( ~1sec ) da einige Gems geladen werden müssen
	Für Entwicklungsumgebung ausreichend.

2. `nativ_objectChangedCallback.tcl`

	Diese implementation verwendet das redis-cli Konsolen Kommando um direkt mit dem Redis zu sprechen, und die 
	geänderten Objekte in die Wartschlage zu schreiben.
	Vorteil:  Arbeitet schneller als die Ruby-Implementation
	Nachteil: Erfordert die Installation von `redis-cli` auf dem Server
	Für Produktive Umgebung empfehlenswert.

Löschen Sie jeweils die Implementation aus ~/CMS-Fiona/instance/default/script/cm/serverCmds/ die nicht verwendet
werden soll.

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`

Solr Erzegut Logs unter dem folgenden Verzeichnis:

	```
	~/apache-solr/cms/logs/solr-8983-console.log
	```

Der Indexer selbst schreibt ein dediziertes Log unter :
	
	```
	RAILS_APP_HOME/log/resque_worker_index_seslucenmy.log
	```

Resque ist über die eigene Applikation unter der folgenden Adresse erreichbar:

	```
	http://localhost:3000/resque
	```

Wenn dieser unter `config/routes.rb` entsprechend eingerichtet ist:

	```
	mount Resque::Server.new, :at => "/resque"
	```


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 bis Version 7.0.2 ) 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.