02. Instalacja i uruchomienie Aplikacji Czytelnika

Przygotowanie do instalacji aplikacji czytelnika systemu dLibra

W rozdziale "Wymagane oprogramowanie" na stronie Instalacja serwera omówiona zostały wymagania odnośnie oprogramowania które musi być dostępne na komputerze na którym będzie instalowana aplikacja czytelnika systemu dLibra.

Instalacja i konfiguracja kontenera aplikacji Apache Tomcat

Dodatkowo należy zainstalować kontener aplikacji Apache Tomcat w wersji 7.0. Zalecamy pobieranie tego programu bezpośrednio ze stron projektu Tomcat. Instalacja w wypadku serwerów Linuxowych sprowadza się do rozpakowania ściągniętego archiwum do docelowego katalogu w którym pracował będzie Apache Tomcat. Dla użytkowników Windows twórcy Apache Tomcat stworzyli wygodny instalator.

Po zainstalowaniu serwera Apache Tomcat należy skonfigurować parametry związane z połączeniami HTTPS które będą realizowane w trakcie działania aplikacji czytelnika. Szczegółowe omówienie tego zagadanienia można znaleźć w dokumencie SSL Configuration HOW-TO.

Instalacja Aplikacji Czytelnika

Na stronie Instalacja serwera w rozdziale "Zawartość dystrybucji" omówiona została zawartość pakietu instalacyjnego systemu dLibra. Przed rozpoczęciem instalacji należy się zapoznać z tym opisem.

Przed przystąpieniem do instalacji należy przygotować plik tekstowy zawierający parametry konfiguracji instalacji serwera systemu dLibra. Plik ten zawiera kolejne wpisy w postaci: <nazwa>=<wartosc>. Każdy wpis powinien znajdować się w osobnej linijce. Szablon tego pliku, zawierający przykładowe wartości niektórych parametrów to wspomniany wcześniej plik sample-webapp.properties znajdujący się w głównym katalogu pakietu dystrybucyjnego.

• serverHostname - adres komputera na którym został zainstalowany serwer dLibry,
• readerPasswd - hasło dostępowe dla aplikacji czytelnika, zostało ono wygenerowane w czasie instalacji serwera dLibry,
• webappDomain - adres domenowy w ramach którego będzie działała aplikacja czytelnika np. dlibra.psnc.pl.
• webappPath - rozwiniecie adresu domenowego w przypadku gdy aplikacja czytelnika będzie działać pod adresem który jest taki sam jak adres domenowy wartość webappPath powinna pozostać pusta. W przeciwnym razie należy tutaj dopisać odpowiedni łańcuch znaków poprzedzając go / (slash). np. biblioteka cyfrowa projektu dLibra działa pod adresem : http://dlibra.psnc.pl/biblioteka. Adres domenowy to dlibra.psnc.pl, a webappPath = /biblioteka.
• httpPort - port na jakim będą realizowane połączenia HTTP, np. 8080.
• httpsPort - port na jakim będą realizowane połączenia HTTPS, np. 8443.
• libraryID - jeżeli biblioteka ma zostać w przyszłości włączona do rozproszonej platformy uwierzytelniania powinna ona posiadać unikalny identyfikator (w skali całej sieci polskich bibliotek cyfrowych).
• webappWorkingDir - katalog roboczy aplikacji czytelnika, tutaj będą zapisywane statystyki zapytań wydawanych przez użytkowników, baza danych aplikacji czytelnika.
• smtpHost, smtpAuthorization, smtpUsername, smtpPassword - parametry związane z wysyłaniem wiadomości email z aplikacji czytelnika.
• fromMail - adres email który będzie wstawiany w pole From wszystkich wiadomości wysyłanych przez aplikacje czytelnika.
• contactFormToMail - lista oddzielonych przecinkami adresów email na które będą rozsyłane wiadomości, które użytkownicy wprowadzą w formularzu kontaktowym.

Uruchomienie instalatora

Aby uruchomić instalator aplikacji czytelnika należy w głównym katalogu pakietu instalacyjnego wydać polecenie ant apps. Po uruchomieniu skryptu instalacyjnego, użytkownik będzie musiał odpowiedzieć na przedstawione poniżej pytania:

Please enter configuration file name:

Odpowiedzią na to pytanie powinna być nazwa pliku (wraz z pełną ścieżką), który zawiera parametry instalacyjne
aplikacji czytelnika (np. /home/dlibra/install/sample-webapp.properties).

Please enter target directory for this installation:

Należy wprowadzić katalog do którego zostaną skopiowane pliki aplikacji czytelnika np. /user/home/dlibra.

Po zakończeniu instalacji w katalogu docelowym powinien znaleźć się podkatalog dlibra-webapp-5.0.x zawierający odpowiednio skonfigurowaną aplikacje czytelnika.

Aplikacja Czytelnika w kontenerze Apache Tomcat

Aby uruchomić aplikacje czytelnika należy dodać odpowiedni plik z jej opisem do serwera aplikacji Apache Tomcat. Plik ten należy umieścić w katalogu: katalog-tomcata/conf/Catalina/localhost, plik ten może mieć dowolną nazwę, jeżeli chcemy aby aplikacja czytelnika była serwowana jako aplikacja domyślna dla zainstalowanego serwera Apache Tomcat należy plik deskryptora nazwać ROOT.xml. Poniżej przykładowy plik ROOT.xml:

<?xml version="1.0" encoding="UTF-8"?>
<Context docBase="sciezka-do-aplikacji-czytelnika">
</Context>

Pierwsze uruchomienie Aplikacji Czytelnika

Bardzo przydatnym poleceniem przy administrowaniu aplikacją czytelnika jest tail (tail posiada swój windowsowy odpowiednik WinTail). Polecenie to pozwala śledzić pliki logów Apache Tomcat, będąc w katalogu głównym Tomcata należy wpisać : tail -f logs/catalina.out. Jeżeli plik catalina.out nie istnieje możemy go samodzielnie utworzyć. Należy teraz uruchomić Apache Tomcat i śledzić postęp pierwszego uruchomienia na konsoli gdzie wydane zostało polecenie tail. Gdy inicjalizacja serwera Tomcat zostanie zakończona : "server started up in" w pasku adresowym przeglądarki wpisujemy adres zgodny z tym co wpisaliśmy w sample-webapp.properties - http://webappDomain:httpPort/webappPath.

Najczęstsze problemy występujące w czasie instalacji

Błędy podczas startu Apache Tomcat 7.0

Przy próbie uruchomienia Aplikacji Czytelnika może zdarzyć się aplikacja nie będzie działała poprawnie, a w logach Tomcata znajdą się komunikaty o błędach zbliżone do poniższych:

...
java.rmi.ServerException: RemoteException occurred in server thread; nested exception is:
java.rmi.UnmarshalException: error unmarshalling arguments; nested exception is:
java.net.MalformedURLException: no protocol: Files/Apache
...

Przyczyną takiej sytuacji jest błąd w JRE, który uniemożliwia wykorzystanie technologii RMI w aplikacjach uruchamianych w Tomcacie, jeżeli jest on zainstalowany w katalogu, który zawiera spacje (np. C:\Program Files\Apache Group\Jakarta Tomcat 7.0). Niestety obecnie jedyną znanym wyjściem z tej sytuacji jest ponowna instalacja Tomcata w katalogu, którego ścieżka nie zawiera znaków spacji. Szczegółowe informacje można znaleźć pod adresem: http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4273532

Nie można się zalogować do panelu administracyjnego

Próba zalogowania lub wejscia na stronę admin kończy się niepowodzeniem, przeglądarka wyświetla komunikat o odrzuceniu połączenia. W takiej sytuacji należy sprawdzić czy konfiguracja HTTPS została przeprowadzona poprawnie.
Najczęstsze błędy popełniane podczas konfiguracji HTTPS to:

1. nie odkomentowany Connector HTTPS w pliku tomcat/conf/server.xml,
2. w katalogu domowym użytkownika, który uruchamiał Apache Tomcat nie ma pliku .keystore,
   1. należy pamiętać, że polecenie wygenerowania certyfikatu dla Apache Tomcat musi być wydane przez tego samego użytkownika, który będzie uruchamiał AT.
3. hasło podawane przy tworzeniu certyfikatu dla AT jest inne niż "changeit"
   1. Wartość "changeit" jest standardowym hasłem wykorzystywanym przez AT do dostępu do pliku .keystore, jeżeli zdecydowaliśmy się użyć innego należy w pliku tomcat/conf/server.xml w znaczniku Connector (odpowiedzialnym za HTTPS) podać hasło którego użyliśmy jako wartość atrybutu keystorePass.

Nie mogę uruchomić aplikacji redaktora

1. Sprawdzić czy z linii poleceń dostępne są polecenia jarsigner i keytool.

Do poprawnego uruchomienia aplikacji redaktora konieczne jest aby oba te narzędzia były dostępne. Jeżeli któregoś z nich nie można swobodnie wywołać z linii poleceń należy program ten zainstalować/dodać do zmiennej systemowej PATH.

W przypadku gdy nie mamy możliwości modyfikacji zmiennej systemowej PATH należy zmodyfikować ścieżki do tych programów w pliku dlibra-webapp/WEB-INF/web.xml.

<context-param>
	<description>
	  Path to keytool tool executable.
	</description>
	<param-name>keytool.executable</param-name>
	<param-value>keytool</param-value>
</context-param>
<context-param>
	<description>
	  Path to jarsigner tool executable.
	</description>
	<param-name>jarsigner.excutable</param-name>
	<param-value>jarsigner</param-value>
</context-param>

Zmiana w web.xml wymaga restart Apache Tomcat. Gdy oba narzędzia będą już dostępne dla aplikacji czytelnika należy:

1. zalogować się do panelu administracyjnego
2. kliknąć w odnośnik "Uaktualnienie aplikacji redaktora/administratora"
3. po zakończeniu operacji wybrać "Uruchom aplikacje redaktora/administratora".

Jeżeli mimo podjętych kroków aplikacja redaktora/administratora nie chce się uruchomić należy się skontaktować z twórcami oprogramowania dLibra.

Błąd podczas startu aplikacji na Debianie

Podczas uruchamiania Aplikacji Czytelnika w systemie operacyjnym Debian Etch może pojawić się błąd podobny do przedstawionego poniżej:

...
java.lang.UnsatisfiedLinkError: /usr/lib/jvm/java-1.5.0-sun-1.5.0.16/jre/lib/amd64/libawt.so: libmlib_image.so: cannot open shared object file: No such file or directory
...

Problem dotyczy jedynie Javy Sun 1.5 zainstalowanej z pakietów dostępnych w Debianie. Może także dotyczyć innych wersji Debiana lub systemów bazujących na Debianie np. Ubuntu.

Rozwiązanie tego problemu jest wykonanie następujących poleceń (dla systemów x86):

sudo ln -s /usr/lib/jvm/java-1.5.0-sun/jre/lib/i386/libmlib_image.so /usr/lib
sudo ldconfig

Szczegółowe informacje i inne możliwe rozwiązania można znaleźć pod adresem: https://bugs.launchpad.net/debian/+source/sun-java5/+bug/162232.

Brak statystyk biblioteki cyfrowej

Jeżeli statystyki biblioteki cyfrowej nie są dostępne, może być to spowodowane przez błąd opisany wcześniej: Błąd podczas startu aplikacji na Debianie.