Updating the dLibra System

In general, updating the dLibra system consists in copying newer file versions to the server and to the Reader Application. In the case of greater changes, it may be necessary to also edit some configuration files. Off course, the user must know which files have been changed and where they should be copied to. In order to avoid potential errors related to erroneous copying of files, we have decided to automate that process as much as possible. For that purpose, we have created the updater of the dLibra system. It is a small application which makes it possible to accelerate the update process. In this document, we discuss the general issues related to the installation and operation of the updater, and we explain how to do updates with the use of that tool.

Please do not start up the updater before you have read the following documentation.

Installing the Updater

In order to install the updater of the dLibra system, you have to download the archive, in the selected format: dlibra-jnlp-updater.zip or dlibra-jnlp-updater.tar.gz. The content of the archive should be placed in any location on the computer on which the dLibra system is installed.

The updater is a Java application which makes use of the JNLP protocol. After the first start-up, all the required libraries will be downloaded to the drive, and for the following start-ups, only the possible changes (corrections) in the updater will be downloaded (not the whole application).

After the unpacking (and before the first start-up), the updater directory should contain the following files:

jnlp-updater.bat

jnlp-updater.sh

The scripts which run the updater for Windows and Linux systems. In the case of Linux system, the chmod +x jnlp-updater.sh command should be called.

netxjar

NETX-LICENSE.TXT

A minimalist implementation of the JNLP protocol which make it possible to use that protocol regardless of the Java Web Start framwork of the Sun Microsystems Inc. company.

updater.properties

The updater configuration (see chater “Before Updating”).

Before Updating

For information about new releases of the dLibra system, see here.

When a new version is published in the update repository (see “The Repository of the dLibra Software”, the RSS channel is also updated. After the new version of the dLibra system has been published, the update process can begin. First, the person doing the update should enter parameter values in the updater.properties file and create an account in the repository of the dLibra software. Please remember that all paths to files/directories should be entered with the use of “/”, regardless of the operating system.

The updater.properties file contains the following configuration parameters:

general.serverHomeDirectory – a directory in which the dLibra server is installed;

general.webappHomeDirectory – a directory in which the Reader Application of the dLibra system is installed;

general.target

The updater can serve two update-related purposes: server or webapp; the server mode starts up a server update (see “Updating the dLibra Server”) while the webapp mode means updating the Reader Application (see “Updating the Reader Application”);

webdav.url – an address for the repository of the dLibra system; and

webdav.username and webdav.password – the user name and the password which make it possible for the user who is doing an update to access the repository of the dLibra system.

Before the actual update process, a backup of the currently installed version of the system should be done.

It is recommended that the dLibra server be updated first, before the Reader Application.

The system makes it possible to do an update within the framework of the same, ‘small’ version and between ‘small’ versions. The small version consists of the two first numbers of a version number, for example, for 6.1.0, the ‘small’ version is 6.1. An update within the framework of a ‘small’ version is done automatically. In order to update the system to another ‘small’ version, for example, from 6.1 to 6.2, a parameter with the required version must be passed on to the updater. If new versions of the same and of another ‘small’ version are available, the user must also indicate which version is to be installed.

An update of a particular version of is enforced with the use of parameter updater.requestedVersion. For example, if we have version 6.1.0 and want to update the system to the 6.2.0 version, we enter the following code in the “updater.properties” file:

updater.requestedVersion=6.2.0

Please remember to delete that entry from the file after the update.

The update process makes it possible to update any version to any other version, as long as there is such a possibility. In the case of an automatic update within the framework of one ‘small’ version, whenever the updater is called, an update to the latest version takes place. For example, when version 5.0.11 is installed, the updater has to be called once for the dLibra server to be updated to the newest version, for example, 6.0.24.

Updating the dLibra Server

The server is updated in the following steps:

1. Do a backup of the currently installed version of the server.
2. End the dLibra server (and the Tomcat server).
3. In the updater.propertiesfile set general.serverHomeDirectory and general.target to value server.
4. Call the script which starts up the updater – it should be the appropriate script for the installed operating system.

When the startup script has been called, the updating process will begin. If it is the first start-up, the updater will first download ‘itself’, and then it will begin the actual updating process. The updating process looks as follows:

1.   The updater determines the parameters of the server (that information is taken mainly from databases; the updater uses information from the database.properties file of the server):
   
   1. Which services are installed?
   2. Does the server work?
   3. Which version of the dLibra system is currently installed? 
2. Are there newer versions in the repository?
   
   1. If not, the updater is ended.
3. The updater connects with the repository of the dLibra software, which contains updates, and downloads the files necessary for the update.
4. The status of the dLibra server is checked:
   
   1. If the dLibra server is running, the updater will wait until it is ended.
   2. If it is ended, the updater will move to the next step of the update.
5. Old files are removed and replaced with new ones.
6. If the person who is doing the update has to intervene, the information about it will be displayed on the console.
   
   1. For each such file:
      
      1. copy of the old file with the "fromVersion_x_x_x_" extension (where x_x_x_ is an old version of the dLibra system, for example, pages.xml.fromVersion_5_0_l_) will be created;
      2. the old file will be replaced with a new one.
7. The update files downloaded to the temporary directory are deleted.
8. At the end of the server update, the program displays information about which server services and Reader Applications are still to be updated (if the dLibra server is installed on more than one computer, the updating process has to be repeated for each of them).
9. That ends the process of the automatic update of the server; if there are newer versions in the repository, the updater will display an appropriate message. 

After the updater has finished its job, the user should review the files indicated by the program as requiring an intervention of the person who is doing the update. After the server has been updated to the latest version, the user can proceed to update the Reader Application.

Updating the Reader Application of the dLibra System

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 aktualizacji Aplikacji Czytelnika, wszystkie instalacje Aplikacji Redaktora i Administratora automatycznie zaktualizują się przy następnym uruchomieniu.

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ść false (domyślna wartość to true), aktualizator pominie etap sprawdzania, 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.