Aktualizacja systemu dLibra

Aktualizacja systemu dLibra w ogólności polega na skopiowaniu do katalogów Serwera i Aplikacji Czytelnika nowych wersji plików. W przypadku poważniejszych zmian konieczna może być też edycja niektórych plików konfiguracyjnych. Trzeba oczywiście wiedzieć które pliki zostały zmienione oraz gdzie je przekopiować.  Aby uniknąć potencjalnych błędów związanych z błędnym kopiowaniem plików, zdecydowaliśmy w możliwie najszerszym zakresie zautomatyzować ten proces. W tym celu stworzony został Aktualizator systemu dLibra. Jest to niewielka aplikacja, która pozwala przyśpieszyć proces aktualizacji. W niniejszym dokumencie przedstawione zostaną ogólne zagadanienia związane z instalacją i działaniem Aktualizatora, oraz to jak wygląda aktualizacja przeprowadzana przy użyciu tego narzędzia.

Proszę nie uruchamiać Aktualizatora zanim nie zapoznają się Państwo z poniższą dokumentacją.

Instalacja Aktualizatora

Aby zainstalować Aktualizator systemu dLibra należy pobrać archiwum w wybranym formacie: dlibra-jnlp-updater.zip lub  dlibra-jnlp-updater.tar.gz. Umieścić jego zawartość w dowolnie wybranej lokalizacji na komputerze na którym zainstalowana jest dLibra.

Aktualizator jest aplikacją Javową wykorzystującą protokół JNLP. Przy pierwszym uruchomieniu, na dysk zostaną ściągnięte wszystkie wymagane biblioteki, każde kolejne uruchomienie spowoduje ściągnięcie już tylko ewentualnych zmian (poprawek) w Aktualizatorze, a nie całej aplikacji.

Po rozpakowaniu (a przed pierwszym uruchomieniem) w katalogu Aktualizatora powinny znajdować się następujące pliki:

jnlp-updater.bat
jnlp-updater.sh

Skrypty uruchamiające Aktualizator dla systemów Windows i Linux. W przypadku systemów Linuxowych należy pamiętać o wywołaniu polecenia chmod +x jnlp-updater.sh przed uruchomieniem skryptu.

netx.jar
NETX-LICENSE.TXT

Minimalistyczna implementacja protokołu JNLP pozwalająca na wykorzystanie tego protokołu niezależnie od Java Web Start firmy Sun Microsystems.

updater.properties

Konfiguracja aktualizatora (por. rozdział "Przed aktualizacją").

Przed aktualizacją

Informacje o nowych wydaniach systemu dLibra znajudją się tutaj.

W chwili gdy nowa wersja jest publikowana w repozytorium aktualizacji (patrz "Repozytorium oprogramowania dLibra") jest również uaktualniany kanał RSS. Po opublikowaniu nowej wersji systemu dLibra możemy rozpocząć proces aktualizacji. W tym celu należy uzupełnić wartości parametrów w pliku updater.properties oraz założyć konto w repozytorium oprogramowania dLibra. Proszę pamiętać, że wszystkie ścieżki do plików/katalogów powinny być zapisane przy użyciu "/" niezależnie od używanego systemu operacyjnego.

Plik updater.properties zawiera następujące parametry konfiguracyjne:

general.serverHomeDirectory -  katalog w którym zainstalowany jest serwer dLibry

general.webappHomeDirectory -  katalog w którym zainstalowana jest Aplikacja Czytelnika systemu dLibra.

general.target

Aktualizator może realizować dwa cele aktualizacji : server lub webapp. Tryb serwer uruchamia aktualizacje serwera (por. Aktualizacja Serwera) natomiast tryb webapp to aktualizacja Aplikacji Czytelnika (por. Aktualizacja Aplikacji Czytelnika).

webdav.url - Adres do Repozytorium oprogramowania dLibra

webdav.username i webdav.password  - Nazwa użytkownika i hasło pozwalające na dostęp do repozytorium oprogramowania dLibra.

Przed przeprowadzeniem właściwego procesu aktualizacji należy najpierw wykonać kopie zapasową obecnie zainstalowanej wersji systemu.

Zaleca się aby w pierwszej kolejności przeprowadzić aktualizacje serwera dLibry, a następnie zakualizować Aplikację Czytelnika.

System umożliwia aktualizację w ramach tej samej tzw. małej wersji, a także pomiędzy małymi wersjami. Na małą wersję składają się dwie pierwsze liczby numeru wersji. przykładowo małą wersją dla 5.1.0 jest 5.1. Aktualizacja w ramach małej wersji następuje automatycznie. Jeżeli chcemy zaktualizować system do innej małej wersji, np z 5.1 do 5.2, musimy przekazać do Aktualizatora parametr z żądaną wersją. Jeżeli dostępne są nowe wersje z samej oraz innej małej wersji to także musimy podać, którą wersję chcemy zainstalować.

Do wymuszenia aktualizacji do określonej wersji służy parametr updater.requestedVersion. Przykładowo, jeżeli posiadamy wersję 5.1.0 i uaktualnic system do wersji 5.2.0, to w pliku updater.properties umieszczamy następujący wpis:

updater.requestedVersion=5.2.0

Należy pamiętać, aby po aktualizacji usunąć ten wpis z pliku.

Proces aktualizacji pozwala na uaktualnienie pomiędzy dowolnymi wersjami, o ile oczywiście jest taka możliwość. W przypadku automatycznej aktualizacji w ramach tej samej małej wersji każdorazowe wywołanie Aktualizatora powoduje uaktualnienie do najnowszej wersji. Przykładowo: mając zainstalowaną wersję 4.0.11,  po jednym wywołaniu Aktualizatora serwer dLibry zostanie uaktualniony do najnowszej wersji, np 4.0.24.

Aktualizacja serwera dLibry

Proces aktualizacji serwera dLibry przebiega następująco:

1.   Wykonać kopie zapasową obecnie zainstalowanej wersji serwera
2.   Zakończyć działanie serwera dLibry (i serwera Tomcat)
3.   W pliku updater.properties ustawić general.serverHomeDirectory oraz general.target na wartość server.
4.   Wywołać skrypt uruchamiający Aktualizator odpowiedni dla zainstalowanego systemu operacyjnego

Po wywołaniu skryptu startowego rozpocznie się procesu aktualizacji. Jeżeli jest to pierwsze uruchomienie Aktualizator ściągnie najpierw "sam siebie", a następnie rozpocznie właściwy proces aktualizacji. Sam proces aktualizacji przebiega następująco:

1.   Aktualizator ustala parametry serwera (Informacje te są pobiera głównie z bazy danych. Aktualizator korzysta z informacji branych z pliku database.propertiesserwera) :
   1. Które usługi są zainstalowane?
   2. Czy serwer działa?
   3. Jaka jest aktualnie zainstalowana wersja dLibry?  
2. Czy w repozytorium są dostępne nowsze wersje?
   1. Jeżeli nie, kończy to pracę Aktualizatora.
3. Aktualizator łączy się z repozytorium oprogramowania dLibra, gdzie znajdują się aktualizacje i ściąga stamtąd pliki niezbędne do przeprowadzenia aktualizacji.
4. Sprawdzany jest stan serwera dLibry:
   1.  Jeżeli serwer dLibry jest uruchomiony, aktualizator będzie czekał, aż zostanie wyłączony.
   2. Jeżeli jest wyłączony przejdzie do kolejnego kroku aktualizacji.
5. Usuwane są stare pliki, a na ich miejsce kopiowane nowe.
6. Jeżeli zmiany w plikach wymagają interwencji osoby przeprowadzającej aktualizacje informacja o tym zostanie wypisana na konsole.
   1. dla każdego takiego pliku:
      1. stworzona zostanie kopia starego pliku z rozszerzeniem "fromVersion_x_x_x_" (gdzie x_x_x_ ) to stara wersja dLibry np. pages.xml.fromVersion_4_0_1_
      2. stary plik zostanie zastąpiony nowym
7. Usuwane są pliki Aktualizacji sciagnięte do katalogu tymczasowego.
8. Na koniec aktualizacji serwera wyświetlana jest informacja o tym, jakie pozostałe usługi serwera oraz Aplikacje Czytelnika trzeba jeszcze zaktualizować (w przypadku gdy serwer dLibry jest zainstalowany na więcej niż jednym komputerze proces aktualizacji trzeba powtórzyć dla każdej z nich).
9. Kończy to proces automatycznej aktualizacji serwera, serwer posiada jest jeżeli w repozytorium znajdują się nowsze wersje Aktualizator wyświetli o tym informacje.  

Po zakończeniu działania Aktualizatora należy przejrzeć pliki, które zostały wskazane przez Aktualizator jako wymagające interwencji osoby przeprowadzającej aktualizacje. Gdy serwer został już uaktualniony do najnowszej wersji możemy przejść do Aktualizacji Aplikacji Czytelnika.

Aktualizacja Aplikacji Czytelnika systemu dLibra

Proces aktualizacji Aplikacji Czytelnika przebiega podobnie jak omówiona w poprzednim rozdziale aktualizacja serwera dLibry.

1. Wykonać kopie zapasową obecnie zainstalowanej wersji Aplikacji Czytelnika.
2. Wyłączyć Tomcata (o ile nie został jeszcze wyłączony)
3. W pliku updater.properties ustawić general.webappHomeDirectory oraz general.target na wartość webapp.
4. Wywołać skrypt uruchamiający Aktualizator odpowiedni dla zainstalowanego systemu operacyjnego

Proces aktualizacji przeprowadzany dla Aplikacji Czytelnika ma bardzo podobny przebieg z pominięciem pewnych kroków charakterystycznych dla serwera. Po zakończeniu procesu aktualizacji dla Serwera i Aplikacji Czytelnika możemy uruchomić system dLibra.

Aktualizacja Aplikacji Redaktora i Administratora

Po uruchomieniu zaktualizowanego systemu dLibra należy jeszcze zaktualizować Aplikację Redaktora i Administratora. W tym celu należy wejść do Panelu Administratora na stronie www (dostępnego po zalogowaniu jako admin, na stronie ze szczegółami konta). Komenda aktualizacji widoczna jest na pierwszej stronie Panelu.

Terminologia

Aktualizator - aplikacja służąca do (prawie) automatycznej aktualizacji systemu dLibra.

Aktualizacja - np. Aktualizacja 3.0.13-3.0.18 - pliki, które zmieniły się między wersją 3.0.13 a 3.0.18.

Repozytorium oprogramowania dLibra - Pod adresem https://dl.psnc.pl/repository/soft/dlibra/ znajdują się wszystkie dotychczas opublikowane wersje systemu.  Począwszy od wersji 3.0 publikowane są tutaj również Aktualizacje (katalog patch dla wersji 5.0).  To właśnie z tych Aktualizacji korzysta omawiane w niniejszym dokumencie narzędzie. Aby uzyskać dostęp do repozytorium oprogramowania dLibra konieczne jest uprzednie założenie konta. Należy w tym celu wysłać prośbę o jego utworzenie na adres dlibra@man.poznan.pl.

Najczęściej zadawane pytania

Co zrobić w przypadku gdy serwer dLibry działa na dwóch maszynach?

Jeżeli serwer dLibry działa na kilku serwerach, aktualizator należy zainstalować na każdym z komputerów, a sam proces aktualizacji powtórzyć dla każdej instancji serwera. Analogicznie należy postąpić w przypadku gdy aplikacja czytelnika jest zainstalowana na innej maszynie niż serwer dLibry.

updater.properties : parametry opcjonalne

server.checkRunning - Jeżeli parametr ten ma wartość true (jest to wartość domyślna) aktualizator pominie etap na którym sprawdza czy serwer jest uruchomiony. Ustawienie tej wartości na false może być pomocne gdy chcemy zaktualizować kopie plików aplikacji czytelnika i serwera. Nie ma wtedy potrzeby wyłączania żadnego z elementów systemu dLibra, a po pomyślnym zakończeniu aktualizacji można zamienić stary plik na nowy.

delete.downloaded.patch - Domyślne zachowanie aktualizatora dla tego parametru reprezentuje wartość true. Aktualizator ściąga z repozytorium oprogramowania dLibra pliki aktualizacji, przy zachowaniu wartości domyślnych tuż przed zakończeniem działania Aktualizator usunie wszystkie ściągnięte pliki. Jeżeli chcemy zachować ściągniętą aktualizacje należy ustawić wartość false. Niezależnie od ustawienia tego parametru przy kolejnym uruchomieniu aktualizatora do którego są sciągne aktualizacje zostanie wyczyszczony.

general.tempDirectoryPath - Aktualizator domyślnie ściąga pliki do katalogu dLibraUpdater jest on tworzony w lokalizacji którą wskazuje zmienna systemowa java.io.tmp (jest to zmienna wirtualnej maszyny javy). W przypadku systemów linuxowych przważnie katalog ten odpowiada wartości zmiennej $TEMP. Aby zmodyfikować katalog do którego zapisywane są aktualizacje należy plik updater.properties i dodać klucz : general.tempDirectoryPath, a jako wartość podać żądany katalog.