Setup einer neuen TOPAS-Kundeninstanz#

Für das Setup wird eine TOPAS-Theme-Installationsdatei benötigt. Bitte sicherstellen, dass diese vorliegt, bevor mit dem Setup begonnen wird.

Es empfiehlt sich, diese Anleitung vor dem Beginn des Setup einmal vollständig durchzulesen, um ggf. Unklarheiten möglichst im Vorfeld des Setup zu beseitigen.

Das Aufsetzen einer neuen Kunden-Instanz erfolgt in folgenden Schritten:

  1. den Webserver vorbereiten
  2. Umgebungsvariablen konfigurieren
  3. Contao und das TOPAS-Theme installieren
  4. Kundenspezifische Konfiguration
  5. Cronjobs einrichten
  6. Individualisierung

1. Den Webserver vorbereiten#

  1. Neues Verzeichnis auf dem Webserver einrichten
  2. Domain und SSL-Zertifikat konfigurieren
  3. Neue Datenbank anlegen
  4. Mercure-Dienst konfigurieren

Neues Verzeichnis auf dem Webserver einrichten#

Im Ordner

/topas24/clients/

ein neues Verzeichnis anlegen.

Darin dann folgenden Pfad anlegen:

live/contao/public/

Der fertige Pfad sollte dann so aussehen:

/topas24/clients/<KUNDENBEZEICHNER>/live/contao/public/

Domain und SSL-Zertifikat konfigurieren#

Die Domain muss so konfiguriert sein, dass diese auf das eben erstellte Verzeichnis (public) zeigt.

Verzeichnis schützen#

Es wird empfohlen einen .htaccess-Passwortschutz für das Verzeichnis einzurichten.

Neue Datenbank anlegen#

Eine neue Datenbank anlegen und die Zugangsdaten für die nächsten Schritte bereit halten.

Mercure-Dienst konfigurieren#

Die Domain der neuen Kundeninstanz muss im Mercure-Script hinzugefügt werden. Dieses befindet sich in folgendem Verzeichnis:

/www/htdocs/w01f9a1b/topas24/topas/hub.topas24.net/bin

Dort die Domain im Schlüssel CORS_ORIGINS zu den bestehenden Domains hinzufügen.

CORS_ORIGINS="https://theme.topas24.net https://drkcr.topas24.net"

Anschließend muss der Mercure-Dienst neu gestartet werden. Hierzu per SSH anmelden und in das Verzeichnis des Dienstes wechseln:

cd /www/htdocs/w01f9a1b/topas24/topas/hub.topas24.net/bin

Die Prozess-ID ermitteln. Diese befindet sich in der Datei pid.

cat pid

Den Dienst beenden:

kill <PROZESS-ID>

Den Dienst starten:

/bin/bash start-mercure.sh

Dienst-Status prüfen:

http://hub.topas24.net:3000/healthz

Wenn der Mercure-Dienst läuft, erzeugt dieser Aufruf eine leere Seite mit Status 200. Dieser Aufruf kann auch für ein Monitoring des Dienstes genutzt werden.

2. Umgebungsvariablen konfigurieren#

Einige Umgebungsvariablen müssen bereits vor der Installation gesetzt werden.

Dazu aus dem Theme-Projekt die Datei .env in den Contao-Ordner des in Schritt 1 angelegten Verzeichnisses kopieren

/topas24/clients/<KUNDENBEZEICHNER>/live/contao/.env

Im selben Ordner eine Datei mit Namen .env.local anlegen:

/topas24/clients/<KUNDENBEZEICHNER>/live/contao/.env.local

Folgendes in die .env.local einsetzen:

DATABASE_URL="mysql://<DB-USER>:<DB-PASSWORD>@<DB-HOST>/<DB-NAME>"
MAIL_FROM_ADDR="webmaster@skg-ev.de"
MAIL_FROM_NAME="TOPAS-Theme"
MERCURE_JWT_SECRET="!ChangeThisMercureHubJWTSecretKey!"

Datenbankzugang einrichten#

In der Zeile DATABASE_URL die Datenbankzugangsdaten aus Schritt 1 eintragen.

E-Mail-Adresse des Systemadministrators#

Die Angaben zu MAIL_FROM_ADDR und MAIL_FROM_NAME müssen zunächst einmal nur gesetzt sein und können später jederzeit angepasst werden.

Mercure Secret#

In der Zeile MERCURE_JWT_SECRET das Secret des Mercure-Servers eintragen. Dieses befindet sich auf dem Webserver im start-mercure.sh Skript in folgendem Ordner.

/www/htdocs/w01f9a1b/topas24/topas/hub.topas24.net/bin

3. Contao und das TOPAS-Theme installieren#

Nun kann Contao und das TOPAS-Theme installiert werden.

  1. Contao-Manager herunterladen und auf den Webserver kopieren
  2. Installation mit dem Contao-Manager durchführen

Hintergrundinformation#

Contao installieren

Contao-Manager herunterladen und auf den Webserver kopieren#

Contao-Manager Download

Die Datei Contao contao-manager.phar auf den Webserver in das public-Verzeichnis kopieren:

/topas24/clients/<KUNDENBEZEICHNER>/live/contao/public/

Nach dem Kopieren umbenennen in contao-manager.phar.php

Nun kann der Contao-Manager über die in Schritt 1 konfigurierte Domain aufgerufen werden:

https://<KUNDEN-DOMAIN>/contao-manager.phar.php

Installation mit dem Contao-Manager durchführen#

Benutzerkonto erstellen#

Ein Benutzerkonto erstellen und ein sicheres Passwort vergeben.

Dieses Konto steht in keinem Zusammenhang mit dem Contao Backend oder Frontend.

Benutzerkonto

Systemprüfung#

Nach erfolgter Systemprüfung muss eine Änderung an der Serverkonfiguration vorgenommen werden.

Daher jetzt noch nicht auf Einrichtung klicken.

Composer-Resolver Cloud deaktivieren#

In der Zeile Serverkonfiguration auf Ändern klicken und im nächsten Schritt den Haken bei "Die Composer Resolver Cloud verwenden" entfernen.

Systemprüfung

Die Änderung speichern.

Installation starten#

Nun auf Einrichtung klicken und die Installation starten.

Verzeichnisse

Prüfen, ob das Installationsverzeichnis korrekt ist. Systemdateien sollten in den Ordner Contao und öffentliche Dateien in den Ordner contao/public installiert werden.

Theme-Installation#

An dieser Stelle muss nun das TOPAS-Theme gewählt werden.

In der Auswahl Theme für Contao auswählen und dann die TOPAS-Theme-Installationsdatei auswählen.

Installation

Contao analysiert nun die Datei. Das Ergebnis sollte in etwa so aussehen:

Upload

Nun die Installation über den Button 'Installieren' starten.

Wichtig:

Es kann ggf. bis zu 5 Minuten dauern, bis der Installationprozess startet. Der Contao-Manager zeigt eine kurze Ladeanimation und zeigt anschließend wieder den Button und daher sieht es so aus, als würde nichts passieren. Hier muss nun trotzdem abgewartet werden bis folgender Bildschirm erscheint:

Upload

Der Contao-Manager installiert nun Contao und die weiteren Softwarekomponenten. Dieser Vorgang kann einige Minuten dauern.

Die Theme-Datenbank importieren#

Der Contao-Manager bietet nun an, die in der Installationsdatei enthaltene Theme-Datenbank zu importieren. In den Angaben unter Verbindungsparameter noch einmal prüfen, ob die korrekte Datenbank verbunden ist und anschließend auf Theme importieren klicken, um den Import zu starten.

Datenbankimport

Datenbankimport

Datenbank-Schema aktualisieren#

Falls eine Meldung über ausstehende Migrationen erscheint, Datenbank prüfen und anschließend die Migration ausführen.

Nach dem Import und etwaigen Migrationen müssen vom Contao-Manager noch einige Datenbank-Änderungen vorgenommen werden. Dies mit dem Button Ausführen starten.

Datenbankimport

Nun sollte folgender Bildschirm anzeigen, dass das Datenbank-Schema aktuell ist.

Auf Weiter klicken.

Datenbankimport

Es erscheint die Meldung, dass bereits ein Contao-Administrator-Konto existiert, da dieses mit dem Theme-Import angelegt wurde.

Auf Weiter klicken.

Backend-Konto

Geschafft :-)

Geschafft

Nun ist das System fertig installiert.

Im Contao-Backend anmelden#

Über den Button Contao-Login im Backend anmelden.

Das Zugangsdaten entsprechen denen des TOPAS-Theme-Systems.

Passwort ändern#

Nach dem ersten Login sollte direkt ein neues Passwort vergeben werden. Dazu rechts oben auf den Benutzernamen klicken und anschließend auf Profil. Ein sicheres Passwort eingeben und speichern. Beim nächsten Login muss dann das neue Passwort eingegeben werden.

Dateiverwaltung konfigurieren#

Unter System → Dateiverwaltung die Ordner 'Inhalte', 'Seitenteaser', 'System' und 'theme' jeweils mit dem Stift bearbeiten und auf 'öffentlich' stellen.

Frontend prüfen#

Über die Domain sollte nun das Frontend aufrufbar sein.

4. Kundenspezifische Konfiguration#

Nun sollten die weiteren Einstellungen aus der Datei .env in der Datei .env.local überschrieben werden. Als Vorlage kann hierzu die .env.local Datei aus dem TOPAS-Theme-System herangezogen werden.

Konfiguration#

.env.local

Einstellung Standardwert Anpassung erforderlich Erläuterung
Framework
APP_SECRET - - wird bei der Contao-Installation automatisch gesetzt
DATABASE_URL - Ja Datenbankzugang, muss vor Installation manuell gesetzt werden (s. 1)
MAILER_DSN - Ja SMTP-Einstellungen für den Mailversand. (s. 2)
Contao
MAIL_FROM_ADDR - Ja E-Mail Adresse des Systemadministrators
MAIL_FROM_NAME - Ja Absendername des Systemadministrators
CONTAO_BACKEND_BADGE_TITLE - Ja Systemname (erscheint im Contao-Backend)
CONTAO_BACKEND_CUSTOM_CSS - - Pfadangabe individuelles Backend-CSS (z.B. /files/theme/backend/lafli-contao-backend-facelift.css)
Mercure
MERCURE_URL https://hub.topas24.net:3000/.well-known/mercure - URL des Mercure-Servers. Muss in der Regel nicht überschrieben werden.
MERCURE_PUBLIC_URL https://hub.topas24.net:3000/.well-known/mercure - URL des Mercure-Servers. Muss in der Regel nicht überschrieben werden.
MERCURE_DSN mercure://default?topic={host}/user/{id}/notifier - Muss in der Regel nicht überschrieben werden.
MERCURE_CLIENT_URL Ja Domain des Kundensystems ohne (https://)
MERCURE_JWT_SECRET Ja Mercure-Secret des Webservers (s. 3)
TOPAS-Core
MEMBER_HOME_DIR files/topas/members - Verzeichnis für Mitglieder-Dateien (z.B. Avatare)
TOPAS-Content-API
TOPAS_CONTENT_API_KEY - Ja API-Key für das TOPAS-Content-System
TOPAS_CONTENT_API_URL https://content.topas24.net/topas-content-api Ja Da das Content-System per htaccess geschützt ist müssen die Zugangsdaten mit in die URL aufgenommen werden.
TOPAS_CONTENT_API_FILES_URL https://content.topas24.net Ja Da das Content-System per htaccess geschützt ist müssen die Zugangsdaten mit in die URL aufgenommen werden.
TOPAS_CONTENT_DIR files/topas/content - Verzeichnis für Dateien aus den Inhalten, die über das TOPAS-Content-System bezogen werden
TOPAS-Frontend
TOPAS_FRONTEND_TOPAS_CUSTOM_TITLE Telematisches Patienten- und Angehörigen System Ja System-Titel für die Ersetzung von Platzhaltern
TOPAS_FRONTEND_TOPAS_CUSTOM_SHORT_TITLE TOPAS Theme Ja Kurzer System-Titel für die Ersetzung von Platzhaltern
TOPAS_FRONTEND_TOPAS_CUSTOM_OPERATOR Sächsische Krebsgesellschaft e.V. Ja Betreibername für die Ersetzung von Platzhaltern
TOPAS_FRONTEND_TOPAS_CUSTOM_OPERATOR_EMAIL info@skg-ev.de Ja Betreiber-E-mail für die Ersetzung von Platzhaltern
TOPAS_FRONTEND_TOPAS_CUSTOM_OPERATOR_URL https://www.skg-ev.de Ja Betreiber-Website für die Ersetzung von Platzhaltern
TOPAS_FRONTEND_TOPAS_CUSTOM_OPERATOR_LOGO files/System/Layout/logo.svg Ja Betreiber-Logo für die Ersetzung von Platzhaltern
Docs-Link
TOPAS_DOCS_LINK_DOCS_URL https://docs.topas24.net - Link zur Dokumentation

5. Cronjobs einrichten#

Für die Artikel-Synchronisation und die Benachrichtigungen müssen zwei Cronjobs eingerichtet werden:

  • contao-cron.php
  • contao-messenger-cron.php

Diese beiden Dateien müssen aus dem public Verzeichnis des Theme-Projekts in das public Verzeichnis der neuen Kunden-Instanz kopiert werden.

In beiden Dateien muss jeweils der Pfad an den Pfad der Kunden-Instanz angepasst werden.

Anschließend müssen beim Hosting-Provider zwei Cronjobs angelegt werden, welche die jeweiligen PHP-Skripte aufrufen.

contao-cron.php sollte einmal in der Nacht laufen. Idealerweise sollten die Cronjobs der jeweiligen Kunden-Instanzen nicht alle zum selben Zeitpunkt laufen.

contao-cron-messenger.php sollte jede Minute ausgeführt werden.

System-User#

TODO: Beschreibung hinzufügen/verbessern

translations/identifier.de.json

Frontend-Benutzer-Account des Betreibers im Backend anlegen und dessen ID in identifier.de.json hinterlegen.

Individualisierung#

Das Setup ist damit abgeschlossen und es kann die weitere Individualisierung erfolgen.