Installation

Sie erhalten den gepackten Ordner terratwin-2.x.x, den Sie direkt auf Ihrem Webserver hosten können. Ohne zusätzliche Anpassungen ist die Anwendung identisch zum Auslieferungszustand, vgl. demo.terratwin.de .

Vorbemerkungen

Dateistruktur

Es bietet sich an, einen Stammordner bspw. terratwin anzulegen und darin jede Version in einem eigenen Unterordner abzulegen. So bleibt die zuvor installierte Version beim Update erhalten und kann bei Problemen sofort wieder aktiviert werden.

Staging-Umgebung

Es empfiehlt sich vor dem Produktivgang eine Staging-Instanz einzurichten, z. B. durch ein zusätzliches virtuelles Verzeichnis im IIS. So können Sie neue Versionen gefahrlos testen und notwendige Anpassungen vornehmen, bevor die Änderungen live gehen.

Installation auf Windows Server (IIS)

Die folgenden Schritte beschreiben die Standardinstallation auf einem Windows Server mit dem Internet Information Services (IIS). Andere Konstellationen sind möglich, werden hier aber nicht behandelt.

Neu ab Version 2.4.1

Dem ZIP-Archiv liegt mit deploy.ps1 ein Assistent bei, der Installation und Update auf Windows Server durchführt. Die Anleitung dazu finden Sie in der beiliegenden deploy.md. Der Assistent befindet sich in der Beta-Phase; die Nutzung erfolgt auf eigene Gefahr. Setzen Sie ihn zunächst nur auf Test- und Staging-Instanzen ein, nicht auf Produktivinstanzen.

Installieren Sie das .NET Hosting Bundle falls noch nicht geschehen.

Neu ab Version 2.4.0

Bisherige Versionen von Terratwin setzten bei der Bereitstellung auf Windows Server auf den HttpPlatformHandler. Da dieser von Microsoft nicht mehr weiterentwickelt wird, setzt Terratwin ab Version 2.4.0 stattdessen auf das ASP.NET Core-Modul (ANCM), das mit dem .NET Hosting Bundle installiert wird.

Entpacken Sie den Ordner terratwin-2.x.x in einem geeigneten Verzeichnis auf Ihrem Server
Öffnen Sie den IIS-Manager (Internet Information Services (IIS) Manager)
Navigieren Sie zu Default Website und stellen Sie sicher, dass diese an den Port 443 gebunden ist. Alternativ können Sie mit Rechtsklick auf Sites eine Neue Site hinzufügen.
Legen Sie mit Rechtsklick auf die gewählte Site ein Neues virtuelles Verzeichnis an. Legen Sie den physischen Pfad zum Ordner terratwin-2.x.x fest und für den virtuellen Pfad einen beliebigen Pfad unter der die Terratwin-Instanz unterhalb erreichbar sein soll.
Navigieren Sie zu Anwendungspools und erstellen Sie einen neuen Anwendungspool mit dem Namen TerratwinApiAppPool. Übernehmen Sie die Einstellungen wie in den Screenshots dargestellt:

Grundeinstellungen für den Anwendungspool

Erweiterte Einstellungen für den Anwendungspool

Navigieren Sie in Ihrem virtuellen Verzeichnis zum Verzeichnis api und konvertieren Sie dieses Verzeichnis in eine Anwendung.
Überprüfen Sie in den Handlerzuordnungen von api, ob der Handler AspNetCoreModuleV2 registriert ist.
Stellen Sie sicher, dass der Benutzer IIS_IUSRS Vollzugriff auf das Verzeichnis terratwin-2.x.x/api hat.
Stellen Sie außerdem sicher, dass in der Delegation von Features die Handlerzuordnungen unter dem Maschinenknoten (IIS-Startseite) auf Lesen/Schreiben gesetzt ist.
Liegt die Instanz nicht in der Site-Wurzel, tragen Sie den virtuellen Pfad als root_path in den Systemeinstellungen ein (vgl. Erste Schritte). Ohne passenden root_path antwortet die API auf jede Route mit 404.

Reverse-Proxy-Betrieb

Betreiben Sie Terratwin hinter einem Reverse Proxy, müssen alle erreichbaren Hostnamen - intern und extern - in den Systemeinstellungen unter security → allowed_hosts eingetragen sein.

Hinterlegen Sie zudem für jeden Host den passenden licenseKey in den Systemeinstellungen und speichern Sie die zugehörigen Lizenzdateien in api/terratwin/license/. Ohne gültige Lizenz startet die Anwendung nicht.

Lizenzkey-Beispiel


{
	[...]
	"licenseKey": [
		{
			"hostname": "example.com",
			"key": "40c10a4e-71d2-4892-b6e1-faa5a693e16f"
		},
		{
			"hostname": "example.de",
			"key": "b1c2d3e4-f5g6-7890-h1i2-j3k4l5m6n7o8"
		}
	],
	[...]
}

brotli für IIS konfigurieren

Befolgen Sie die Anleitung von Microsoft zur Konfiguration von brotli für IIS. Beachten Sie, dass im Vorfeld die Rollen Static Content Compression und Dynamic Content Compression installiert sind.

Erforderliche Rollen für die Komprimierung in IIS

Optional können Sie zusätzlich die MIME-Typen application/wasm und application/json komprimieren lassen. Ergänzen Sie diese dazu im IIS-Manager unter Servername → Konfigurations-Editor → system.webServer/httpCompression → staticTypes mit enabled = True und klicken Sie anschließend auf Übernehmen. Beachten Sie, dass diese Einstellung serverweit für alle Anwendungen gilt.

Ergänzen der MIME-Typen im Auflistungs-Editor

WebSocket aktivieren

new@2.4.0

Für die Kommunikation des Chatbots mit Terratwin-AI ist das WebSocket Protokoll erforderlich. Installieren Sie dieses Feature für IIS, wenn noch nicht erfolgt.

Aktivieren der Serverrolle WebSocket Protocol

Installation auf Linux Server

Für den Betrieb unter Linux wird Terratwin ausschließlich als Container-Image ausgeliefert; eine native Installation wie unter Windows ist nicht vorgesehen. Die Images liegen in einer privaten Registry, für die wir Ihnen auf Anfrage einen Zugang einrichten. Dort erhalten Sie auch die vollständige Einrichtungsanleitung samt vorbereiteter docker-compose.yml.

Da die Einrichtung von Ihrer Zielumgebung abhängt, stimmen wir sie individuell mit Ihnen ab. Wenn Sie Terratwin unter Linux betreiben möchten, sprechen Sie uns daher bitte vorab an: Kontakt aufnehmen