Inhaltsverzeichnis
- Einleitung
- Systemanforderungen
- Docker
- COYO Home-Verzeichnis
- Benutzerverzeichnis und Authentifizierung
- REST API
1. Einleitung
Willkommen in eurer neuen digitalen Heimat: COYO!
Dieses Dokument gibt euch als Systemadministratoren einige grundlegende Informationen über das eigene Hosting von COYO, die Systemanforderungen, Docker selbst und wie wir Anwendungsvirtualisierung einsetzen. Außerdem erhaltet ihr einige einführende Informationen zu Backups, Updates, Benutzerverzeichnis, Benutzerauthentifizierung und unserer REST-API.
Alle werden mit hilfreichen Links zu unserer Wissensdatenbank und Dokumentation versorgt.
Wir hoffen, alle eure Fragen zum Hosting von COYO und der Funktionsweise dahinter beantworten zu können und empfehlen euch, Notizen zu machen, wenn etwas nicht klar ist.
2. Systemanforderungen
Anforderungen an die Server-Software
COYO ist als Docker-Komposition erhältlich und kann überall dort eingesetzt werden, wo Docker Compose verfügbar ist. Derzeit ist dies Linux und Mac OS, aber wir empfehlen nur Linux-Distributionen. Wir haben gute Erfahrungen mit Ubuntu, Debian, RedHat, SLES und CentOS gemacht.
Windows Server ist aufgrund fehlender Docker Compose Komponenten nicht möglich.
Anforderungen an die Server-Hardware
Unsere Mindestanforderungen an die Hardware für einen einzelnen Host basieren auf der Anzahl der regelmäßigen Benutzer auf eurem COYO.
Wenn ihr den optionalen Metriken Stack ausführen möchten, um Daten wie CPU-Last, RAM-Nutzung und Backend-Einblicke zu sammeln, benötigen ihr 10 GB zusätzlichen RAM und 2 zusätzliche Kerne. Weitere Informationen zu unserem Metriken Stack findet ihr im Abschnitt 4 Third-Party Container.
Anforderungen an den Client-Browser
*IE11 wird unterstützt, aber nicht empfohlen. Für ein besseres Benutzererlebnis verwendet EDGE oder einen anderen modernen Browser.
Das ist alles, was euer Client braucht.
3. Docker
Eine andere Art der Virtualisierung
Docker wird verwendet, um Anwendungspakete namens "Container" auszuführen. In einem typischen exemplarischen Anwendungsfall betreibt ein Container einen Webserver und eine Webanwendung, während ein zweiter Container einen Datenbankserver betreibt, der von der Webanwendung verwendet wird. Container sind voneinander isoliert und bündeln ihre eigenen Tools, Bibliotheken und Konfigurationsdateien und können über klar definierte Kanäle miteinander kommunizieren. Alle Container werden von einem einzigen Betriebssystemkern betrieben und sind damit leichter als virtuelle Maschinen, es gibt eher eine Virtualisierung von nur einer Anwendung als von einem ganzen Betriebssystem. Container werden aus "Images" erstellt, die ihren genauen Inhalt angeben. Images werden oft durch Kombination und Modifikation von "Base-Images" erstellt, die aus Repositorien heruntergeladen wurden.
COYO ist eine Java-basierte Anwendung, die als Docker-Container verfügbar ist und zusammen mit anderen containerisierten Anwendungen wie PostgreSQL (Datenbank) und MongoDB (Filestore) mit Docker-Compose inszeniert wird.
Hinweis:
Mehr zu Docker erfahrt ihr auch hier.
3.1 Docker-Compose
Ein Werkzeug zur Definition und Ausführung von Multi-Container-Docker-Anwendungen
Compose ist ein Werkzeug zur Definition und Ausführung von Multi-Container-Docker-Anwendungen. Mit Compose verwendet ihr eine YAML-Datei, um die Dienste eurer Anwendung zu konfigurieren. Anschließend erstellt und startet ihr mit einem einzigen Befehl alle Dienste aus eurer Konfiguration.
Mit jedem Release stellen wir eine vorkonfigurierte YAML-Datei mit dem Namen "docker-compose.yml" zur Verfügung, die eine Art Vorkonfiguration für unsere Orchestrierung von Docker-Containern ist.
Die Compose-Datei enthält alle Konfigurationsdetails wie öffentliche Ports, virtuelle Netzwerkeinstellungen, Containerlinks, damit sie miteinander kommunizieren können, Volume Mounts und nicht zu vergessen die Umgebungsparameter für die Dimensionierung und Konfiguration von tieferen Komponenten wie dem Backend JVM.
Um euch einen Eindruck von dieser Technologie zu vermitteln, zeigen wir euch den Load Balancer-Teil unserer aktuellen Compose-Datei:
- services: Enthält alle unsere Container, die wir orchestrieren wollen.
- coyo-lb: Ist der Hostname des Containers, so dass wir diese Abkürzung z.B. beim Verlinken verwenden können.
- image: Definiert, aus welchem Image der Container erstellt wird.
- environment: Hier kommen eure spezifischen Konfigurationen zum Einsatz. Wir liefern eine zusätzliche Datei, in der alle Parameter mit Werten gefüllt werden.
- links: Definiere, mit welchen Containern dieser Container über alle Ports innerhalb des virtuellen Docker-Netzwerks kommunizieren kann.
- volumes: Definiert Mounts in den virtuellen Docker-Container. Diese sind wichtig, da alle Daten beim Entfernen eines Containers verloren gehen, außer wenn einige Volumes vom Host in den Container einhängt werden.
- ports: Definition der offenen Ports. In diesem Fall ist dies also unser Load Balancer und wir wollen, dass er den gesamten HTTP-Verkehr verarbeitet, so dass die Ports 80 und 443 geöffnet werden. Die anderen Ports sind für andere öffentlich zugängliche Dienste bestimmt.
3.2 Docker Netzwerk
Docker erstellt standardmäßig eine virtuelle Netzwerkbrücke und weist den Containern dynamisch IP-Adressen zu. Dieses Netzwerk ist von außerhalb des Hosts nicht erreichbar. Um Container öffentlich zugänglich zu machen, müsst ihr ein Port Mapping konfigurieren. Mit unserer Compose-Datei erstellt Docker-Compose ein virtuelles Netzwerk namens "coyo-default", in dem nur der Loadbalancer veröffentlicht wird. Ohne weitere Konfiguration ist der IP-Bereich für alle Container 172.19.0.0.0.0/24.
Wenn ihr COYO mit einem HTTP(S)-Proxy betreiben wollt, schaut in diesen Artikel.
Loadbalancer
Alle eingehenden Verbindungen gehen über den COYO-Loadbalancer. Dieser erzwingt eine SSL-Verbindung, sodass ihr ein gültiges Zertifikat benötigt, um COYO in unserem Standard-Setup auszuführen. Es ist aber möglich dies neu zu konfigurieren, um den Proxy eures Unternehmens zu verwenden. Wenn ihr die Konfiguration unseres COYO Loadbalancer (Haproxy) ändern möchtet, müsst ihr die .conf-Datei beibehalten und Anpassungen vornehmen.
Neben den HTTP(S)-Ports 80 und 443 akzeptiert der Loadbalancer Verbindungen zu den folgenden Ports:
- 5601 - Kibana: Hier findet ihr die Protokolle aller Container.
- 5602 - Grafana: Dort findet ihr Metriken wie CPU und Speicherauslastung aller Container.
- 8083 - COYO Backup: Hier könnt ihr die Backups über eine REST-API erstellen und wiederherstellen.
- 15672 - RabbitMQ Frontend: Dort findet ihr eine Übersicht über das RabbitMQ.
Alle anderen Dienste wie Datenbank und Filestore sind von außerhalb des Hosts nicht zugänglich.
3.3 COYO Container
COYO stack
Diese Container sind das Herzstück von COYO. Es besteht aus Backend, Frontend, Push, Dokumentation und Backup.
- Push: Verarbeitet Push-Meldungen an euer Smartphone. Um diese Funktion nutzen zu können, müsst ihr unseren Service über unseren Service Desk kontaktieren und nach einem PUSH API JSON Schlüssel fragen. Diesen Schlüssel könnt ihr in eure .env-Datei einfügen.
- Docs: Enthält die Dokumentation, die ihr findet, wenn ihr in eurem COYO auf "Hilfe" klickt.
- Backup: Erstellt ein Backup, bei dem die gesamte Datenbank und der Filestore gesichert wird.
Hinweis:
In unserer Knowledgebase findet ihr einen hilfreichen Artikel darüber, wie ihr ein Backup erstellen und wiederherstellen könnt.
3.4 Third-Party Container
Abhängigkeiten
Dies sind die obligatorischen Abhängigkeiten, um COYO auszuführen.
- PostgreSQL: Unsere Datenbank zur Speicherung aller Inhalte von COYO mit Ausnahme von Dateien.
- MongoDB: Speichert alle Dateien.
- Elasticsearch: Eine Volltextsuchmaschine, die wir für die Suche in COYO nutzen.
- RabbitMQ: Ist ein Nachrichtenbroker.
- Redis: Eine In-Memory-Datenstrukturdatenbank, die wir für das Session-Caching verwenden.
Logging Stack (ELK)
ELK alias Elastic Stack wird am häufigsten in der Protokollanalyse in IT-Umgebungen eingesetzt und besteht aus drei verschiedenen Open-Source-Projekten. Mit diesem Stack könnt ihr eure Protokolldateien aller Container mit einem Webinterface einfach durchsuchen:
- Elasticsearch: Eine NoSQL-Datenbank, die auf der Lucene-Suchmaschine basiert.
- Logstash: Ein Log-Pipeline-Tool, das Eingaben aus verschiedenen Quellen entgegennimmt, verschiedene Transformationen durchführt und die Daten in verschiedene Ziele exportiert.
- Kibana: Eine Visualisierungsebene, die auf Elasticsearch aufbaut. Ihr könnt durch alle Protokolle aller Container blättern, die von der Suchsyntax von lucene verwendet werden. Ihr findet das Webinterface hinter dem Port 5601.
Hinweis:
Mehr zur Lucene Suchsyntax erfahrt ihr hier (Artikel auf Englisch):
Metriken Stack (PROM) - Optional
Überwacht euer COYO mit dem PROM-Stapel! Da dieser Stapel zusätzliche RAM-Ressourcen benötigt und ihr bereits ein Überwachungstool in eurem Unternehmen verwenden könntet, ist dieser Stapel optional und kann mit dem erweiterten Startskript gestartet werden. Das findet ihr in jedem unserer Releases.
Interessante Kennzahlen über euer COYO findet ihr in unseren vorkonfigurierten Grafana-Dashboards, bspw. CPU- und Speicherauslastung der einzelnen Container und viele weitere detaillierte Informationen.
- Prometheus: Ist eine Zeitreihendatenbank, die für die schnelle, hochverfügbare Speicherung und Abfrage von Zeitreihendaten in Bereichen wie Betriebsüberwachung und Anwendungsmetriken optimiert ist.
- Grafana: Ist ein Open-Source Software, universelles Dashboard und Graph Composer, der als Webanwendung läuft. Ihr findet das Webinterface hinter dem Port 5602.
- Node-Exporter: Prometheus-Exporteur für Maschinenmetriken, geschrieben in Go mit steckbaren Metriksammlern.
- cAdvisor: Analysiert den Ressourcenverbrauch und die Leistungsmerkmale von laufenden Containern.
- Postgres-Exporteur: Postgres Metriken-Exporteur für Prometheus.
- Elasticsearch-Exporteur: Elasticsearch Statistik-Exporteur für Prometheus.
- Mongodb-Exporteur: MongoDB-Exporteur für Prometheus.
- RabbitMQ-Exporteur: RabbitMQ-Exporteur für Prometheus
- Redis-Exporteur: Redis Metrics-Exporteur für Prometheus.
- Jolokia-Exporteur: Jolokia-Exporteur für Prometheus.
4. COYO Home-Verzeichnis
Jedes COYO-Release enthält ein Zip-Paket mit Start-/Stopp-Skripten der bereits erwähnten Compose-Datei und der wichtigen .env-Datei, in der all eure Umgebungsparameter mit Standardwerten eingestellt sind.
- start.sh: Das Skript "start.sh" liest die .env und führt den Befehl "docker-compose up" aus, um alle notwendigen Container zu starten, die COYO zum Ausführen benötigt. Wenn die Bilder nicht lokal verfügbar sind, zieht Docker automatisch die Bilder wie in der Compose Datei angegeben.
- start-ADVANCED.sh: Das Skript "start-advanced.sh" führt das Skript "start.sh" aus und startet zusätzlich den Metrikenstapel mit Grafana.
- stop.sh: Das Skript stop.sh führt den Befehl "docker-compose stop" aus, um alle laufenden Container zu stoppen.
- Docker-compose.yml: Diese Datei definiert das Setup und die Version von COYO. Alle Parameter, die ihr konfigurieren müsst, haben wir in die .env-Datei ausgelagert, sodass ihr hier normalerweise keine Anpassungen vornehmen müsst. In Kapitel 3.1 findet Ihr weitere Informationen.
- .env: Die .env-Datei enthält alle konfigurierbaren Parameter, die für den Betrieb von COYO notwendig sind. Um COYO zu konfigurieren, müsst ihr die .env-Datei bearbeiten, in der ihr die Standardwerte mit eurer individuellen Konfiguration überschreibt. Weitere Details zur .env-Datei findet ihr in der Datei README.MD.
4.1 Update COYO
Wenn ihr auf eine neue Version von COYO aktualisieren möchten, müsst ihr nur das Zip-Paket herunterladen.
Erstellt einfach ein Backup (Anleitung), stoppt COYO mit unserem mitgelieferten stop.sh-Skript und entpackt sowie ersetzt alle oben genannten Dateien. Es wird dringend empfohlen, die .env-Datei auf neue Parameter zu überprüfen, die in der .env-Datei angepasst werden müssen. Die Änderungen der Parameter, die wir mit jedem Release vorgenommen haben, findet ihr in unseren Release Notes.
5. Benutzerverwaltung und Authentifizierung
Benutzerverwaltung
Wenn ihr COYO zum ersten Mal startet, wird ein lokales Benutzerverzeichnis verwendet. Wenn ihr ein externes Benutzerverzeichnis hinzufügen möchtet, ist das kein Problem:
COYO unterstützt das Protokoll LDAP(S) für die Benutzerprovisionierung, sodass Verzeichnisse wie MS Active Directory, MS Azure AD und OpenLDAP problemlos zu integrieren sind.
Hinweis:
Hier findet ihr die Anleitung
Authentifizierung
Neben der lokalen Authentifizierung mit Benutzern des lokalen Benutzerverzeichnisses, authentifizieren sich Benutzer von externen Benutzerverzeichnissen gegenüber eurem COYO über LDAP(S) und ihr könnt auch andere Authentifizierungsanbieter hinzufügen.
COYO unterstützt die Authentifizierung über SAML 2.0 und OpenID mit seinem OAuth 2.0-Standard, sodass ihr MS Office SSO, MS ADFS, Google, Facebook, LinkedIn und so weiter problemlos integrieren könnt.
Hinweis:
Eine Anleitung findet ihr hier.
6. REST API
Unsere REST-API stellt euch einige zusätzliche Verwaltungsfunktionen zur Verfügung, wie z.B. die Neuindizierung der Suchindizes oder den Status des Servers. Außerdem ist es möglich, alle Funktionen zu nutzen, die COYO im Web anbietet sowie die Profilfelder der Benutzer anzupassen.
Hinweis:
Mehr Informationen erhaltet ihr in unserer Dokumentation.