Bereitlegen des Deployment Packages

Zunächst muss das Deployment Package ('atlasfx.war') auf dem Rechner bereitgelegt werden, auf dem Sie das atlasFX Update durchführen möchten. Der Download Link wird im Rahmen der Bekanntmachung des atlasFX Release herausgegeben.

Anpassen der Konfiguration

Da atlasFX seit Version 1.7.6 keinen internen LDAP-Server bereitstellt, muss diese Funktionalität aus der 'config.properties'-Datei entfernt werden. Ab Version 1.7.6 stellt atlasFX stattdessen eine effiziente Benutzerverwaltung basierend auf der atlasFX Datenbank bereit.

Auffinden der 'config.properties'-Datei

Falls Sie genau wissen, wo diese Datei liegt, können Sie diesen Abschnitt überspringen.

Sie finden diese Datei im atlasFX Home-Verzeichnis. Das atlasFX-Home-Verzeichnis wurde bei der Installation von atlasFX festgelegt. Falls Ihnen die Installationsdokumentation nicht vorliegt, müssen Sie zunächst das Verzeichnis suchen. Falls Sie über die entsprechenden Java-Kenntnisse verfügen, schauen Sie einfach nach, welcher Wert im System Property ATLASFX_HOME an die atlasFX Web Application übergeben wird.

In der Variable ATLASFX_HOME wird der Pfad zum atlasFX Home-Verzeichnis übergeben. Meist wird diese Variable in der Konfiguration der verwendeten Servlet Engine gesetzt. Sollten Sie nicht über die entsprechenden Kenntnisse verfügen, verwenden Sie bitte die für Ihr Betriebssystem üblichen Suchmechanismen um die Datei 'config.properties' zu finden.

Falls Sie eine oder mehrere Dateien mit diesem Namen gefunden haben, müssen Sie verifizieren, ob es sich tatsächlich um die aktuell von atlasFX verwendete Konfigurationsdatei handelt. Dazu benennen Sie die Datei in 'config.properties_' um und versuchen atlasFX zu starten. Falls atlasFX bereits läuft, muss atlasFX vorher gestoppt werden. Ohne die Datei 'config.properties' kann die Web Application nicht starten. Sollte der Start fehlschlagen ist die soeben umbenannte Datei wahrscheinlich die zuvor verwendete 'config.properties'-Datei. Nun ändern Sie den Dateinamen von 'config.properties_' zurück in 'config.properties' und versuchen Sie, die atlasFX Web Application erneut zu starten.

Startet die Anwendung fehlerfrei, können sie davon ausgehen, dass vermutlich die jeweils umbenannte Datei, die verwendete 'config.properties'-Datei ist. Startet die Web Application nun auch nicht, liegt vermutlich ein anderer Fehler vor. Nun muss zunächst die Anwendung wieder lauffähig gemacht werden, bevor Sie hier weiter fortfahren können. Wenn das System wieder intakt ist, beginne Sie mit "Anpassen der Konfiguration" erneut.

Entfernen der LDAP-Server Konfiguration

Es handelt sich bei dieser Konfiguration um den ehemals in atlasFX integrierten LDAP-Server. Externe LDAP-Server, die zu Autorisierung verwendet werden sollen, sind hiervon nicht betroffen.

Legen Sie zunächst eine Sicherung der Datei 'config.properties' an. Öffnen sie anschießend die 'config.properties'-Datei in einem Texteditor Ihrer Wahl. Entfernen Sie nun alle Zeilen, die mit 'usermanagement.ldap' beginnen. Anschießend muss eventuell noch das Property 'usermanagement.type' angepasst werden, falls es den Wert 'internal' aufweist. Stellen Sie hier den Wert 'sql' ein. Bitte beachten Sie, dass bei dieser Migration alle bisherigen Benutzer- und Gruppendaten verloren gehen und neu eingepflegt werden müssen.

Nun können Sie das Update auf die aktuelle Version von atlasFX durchführen.

Anpassen der server.xml

Mit atlasFX 3.1 wurden Änderungen vorgenommen, die eine Anpassung der server.xml erforderlich machen.

Öffnen Sie die Apache Tomcat Server-Konfiguration in einem Text-Editor.

Suchen Sie nach folgendem Connector-Eintrag

<Connector protocol="HTTP/1.1" ... maxPostSize="0"/>

Suchen sie die Deklaration des Connector für http. Fügen sie dort das Attribut maxPostSize mit dem Wert 0 ein. Diese Konfiguration ist bis auf weiteres für alle neuen atlasFX-Versionen erforderlich.

Durchführung des Updates

Entfernen vorbereiten & durchführen

Zunächst muss die vorhandene Web Application entfernt werden. Für den Zeitraum des Updates ist eine Downtime einzuplanen, da die Web Application vorrübergehend nicht erreichbar sein wird. Das Deployment Package ('atlasfx.war'-Datei) des bestehenden Systems muss auf jeden Fall gesichert werden, um bei Problemen mit dem Update gegebenenfalls die alte 'atlasfx.war'-Datei zurückspielen zu können.

Nachdem die 'atlasfx.war'-Datei aus dem 'webapps'-Verzeichnis entfernt wurde, soll der Tomcat die Web Application entfernen. Dieser Vorgang kann eine gewisse Zeit in Anspruch nehmen. Typischerweise kann der Entfernungsprozess zwischen wenigen Sekunden und 3 Minuten dauern. Die Web Application ist dann erfolgreich entfernt, wenn das Verzeichnis 'atlasfx' aus dem Verzeichnis 'webapps' verschwunden ist.

Sollte das Verzeichnis 'atlasfx' nicht automatisch entfernt werden, verwenden Sie bitte die Dokumentation der Servlet Engine, um das weitere Vorgehen bezüglich des Entfernens der Web Application festzulegen.

Einspielen der Web Application

Nachdem die Servlet Engine für das Einspielen der Web Application vorbereitet wurde, kann nun die neue 'atlasfx.war'-Datei eingespielt werden. Dazu verschieben Sie die zuvor bereitgelegte neue 'atlasfx.war'-Datei in das 'webapps'-Verzeichnis des Tomcat. Nun soll die Tomcat-Anwendung automatisch mit dem Deployment der Web Application beginnen. Typischer Weise kann dieser Prozess zwischen wenigen Sekunden und 5 Minuten dauern. Während des Einspielens wird automatisch das Verzeichnis 'atlasfx' im 'webapps'-Verzeichnis angelegt. Der Deployment-Prozess ist dann erfolgreich abgeschlossen, wenn die Web Application wieder erreichbar ist. Unter Umständen ist zu diesem Zeitpunkt die Anwendung noch nicht voll funktionsfähig, so dass Fehlermeldungen wie http Status 500 oder Fehler innerhalb der Anwendung nicht auf ein fehlerhaftes Deployment hinweisen. Die Ursachen dieser Fehler werden im Zuge der Nachbereitung des Updates behoben, mit der Sie nun fortfahren können. Sollte die Web Application jedoch nicht erreichbar sein beziehungsweise nicht deployed werden können, fahren Sie mit den in der Dokumentation Ihrer Servlet Engine beschriebenen Schritten fort.

Nachbereitung

Damit die atlasFX Web Application den vollen Funktionsumfang zu Verfügung stellen kann, müssen typischerweise die Datenstruktur der atlasFX Datenbank und die atlasFX Tools in der atlasFX Datenbank aktualisiert werden.

Dazu öffnen Sie die atlasFX Administrationsoberfläche. Sie finden die atlasFX Administrationsoberfläche unter der URL 'http(s)://<host>(:<port>)/<path>/cms/admin/'. Sie benötigen dazu die Zugangsdaten, die auch für das Login in das CMS verwendet werden. Folgen Sie zunächst dem Link 'Upgrade the atlasfx-installation' auf der Startseite der Administrationsoberfläche.

Prüfen Sie zunächst, ob eine Aktualisierung der atlasFX Datenbankstruktur notwendig ist. Dazu schauen sie unter dem Punkt 'Database migration' nach, ob dort ein 'pending upgrade script' sowie der Button 'Execute migration' angeboten wird. Ist das nicht der Fall und wird die Meldung 'No migration needed. Schema is up to date.' angezeigt, ist keine Aktualisierung der Datenbankstruktur notwendig und Sie können mit dem Anlegen eines Datenbank-Backups durch Klick auf den Button 'Backup database' fortfahren. Ist stattdessen eine Aktualisierung erforderlich klicken Sie auf 'Execute migration' um die Aktualisierung durchzuführen und prüfen Sie anschließend ob weitere Aktualisierungen der Datenbankstruktur angeboten werden. Führen sie diese gegebenenfalls aus. Bei der Aktualisierung der Datenbankstruktur wird automatisch ein Datenbank-Backup angelegt, so dass Sie nun mit der Aktualisierung der Tools fortfahren können.

Weil die atlasFX Tools in der atlasFX Datenbank verwaltet werden, müssen diese zu jedem Update der Web Application in die bereits vorhandene atlasFX Datenbank eingespielt werden. Dazu klicken Sie auf den Botton 'Import tools' im Bereich 'Tool upgrade'.

Nun sind die notwendigen Aktualisierungen der atlasFX Datenbank abgeschlossen. Prüfen Sie nun ob das System ordnungsgemäß funktioniert.

Einrichten der Standortsuche

In der Auslieferungskonfiguration muss die atlasFX-webapp (server-seitig) Zugriff auf http://tasks.arcgisonline.com/ArcGIS/rest haben, damit die Lokalisierung funktioniert. Falls es nicht möglich ist, den Zugang zu http://tasks.arcgisonline.com/ArcGIS/rest einzurichten, kann ein eigener Geocode Service verwendet werden. Ein Geocode Service ist standardmäßig bei ArcGIS for Server dabei. Zur Konfiguration müssen folgende Zeilen in der Datei config.properties vorhanden sein:
gis.rest.geometryService.url = http://<host>:<port>/<path>/rest
gis.rest.geometryService.folder = <folder falls vorhanden>
gis.rest.geometryService.serviceName = <serviceName>

Beispiel:
gis.rest.geometryService.url = http://arcgisserver.example.com:6080/arcgis/rest
gis.rest.geometryService.folder = Utilities
gis.rest.geometryService.serviceName = Geometry

Falls eine Zugriffskontrolle per Token eingerichtet ist sind weitere Parameter erforderlich:
gis.rest.geometryService.token.serviceUrl = http://<host>:<port>/<path>/tokens/
gis.rest.geometryService.token.user = <user>
gis.rest.geometryService.token.password = <password>

Beispiel:
gis.rest.geometryService.token.serviceUrl = http://arcgisserver.example.com:6080/arcgis/tokens/
gis.rest.geometryService.token.user = der-benutzer
gis.rest.geometryService.token.password = sicheres-password