Praxisleitfaden mit Architektur, WAR-Deployment, PostgreSQL-Anbindung, Nginx Reverse Proxy und TLS-Härtung

1. Einleitung

Mit XWiki steht eine leistungsfähige Open-Source-Plattform für Wissensmanagement, technische Dokumentation und kollaborative Zusammenarbeit zur Verfügung. Durch den modularen Aufbau, die umfangreiche Rechteverwaltung und den integrierten Erweiterungsmechanismus eignet sich XWiki sowohl für interne Dokumentationsplattformen als auch für komplexe Unternehmensumgebungen.

Gerade im Kontext digitaler Souveränität gewinnen kontrollierbare und langfristig wartbare Plattformen zunehmend an Bedeutung. Viele Organisationen hinterfragen bestehende Abhängigkeiten von proprietären Cloud-Lösungen und suchen nach Alternativen, die sich vollständig unter eigener Kontrolle betreiben lassen.

XWiki positioniert sich dabei als mögliche Open-Source-Alternative zu Atlassian Confluence. In Kombination mit OpenProject entsteht zusätzlich eine umfassende Plattform für Projektmanagement, Dokumentation und Kollaboration. Während XWiki die strukturierte Wissensverwaltung übernimmt, bildet OpenProject Aufgabenverwaltung, Ticketing, Roadmaps und Projektsteuerung ab.

Im produktiven Betrieb ist jedoch nicht allein die Funktionalität entscheidend. Ebenso wichtig ist ein sauberer technischer Aufbau, der langfristig wartbar, sicher und supportfähig bleibt. Eine XWiki-Instanz besteht aus mehreren Komponenten, die korrekt zusammenspielen müssen: Java als Laufzeitumgebung, Apache Tomcat als Servlet-Container, PostgreSQL als Datenbank und Nginx als Reverse Proxy für den externen Zugriff.

In diesem Beitrag wird eine klassische Installation von XWiki als WAR-Deployment beschrieben. Dabei wird bewusst auf die einzelnen Komponenten eingegangen, damit nachvollziehbar bleibt, welche Aufgaben sie übernehmen und warum bestimmte Entscheidungen für produktive Umgebungen sinnvoll sind.

Die Installation wird anhand der drei großen Linux-OS-Familien betrachtet:

  • Debian-basierte Systeme
  • Red-Hat-basierte Systeme
  • SUSE-basierte Systeme

Besonderes Augenmerk liegt auf:

  • einer supportfähigen LTS-Installation
  • einem lokalen Tomcat-Backend
  • einer sauberen PostgreSQL-Anbindung
  • einer gehärteten Nginx-Konfiguration mit TLS
  • einer klaren Trennung zwischen Web-, Applikations- und Datenbank-Schicht

Die spätere Automatisierung dieser Schritte mit Ansible wird in einem folgenden Beitrag behandelt.

2. Ziel des Beitrags

Ziel dieses Beitrags ist nicht nur, XWiki „zum Laufen“ zu bringen. Vielmehr soll eine nachvollziehbare Grundlage für produktive Installationen geschaffen werden.

Gerade beim WAR-Deployment ist es wichtig zu verstehen, welche Komponenten beteiligt sind und welche Verantwortung sie jeweils übernehmen.

  • Tomcat stellt die Anwendung bereit
  • PostgreSQL speichert Inhalte und Metadaten
  • Nginx bildet die sichere Zugriffsschicht nach außen

Diese klare Trennung erleichtert:

  • Fehleranalyse
  • Updates
  • Sicherheits-Härtung
  • Monitoring
  • spätere Automatisierung

Der Beitrag richtet sich daher an:

  • Administratoren
  • Dienstleister
  • technische Entscheider
  • Betreiber produktiver Linux-Infrastrukturen

die XWiki nicht nur testen, sondern langfristig stabil betreiben möchten.

3. Produktive Betriebsmodelle und Supportfähigkeit

XWiki kann grundsätzlich auf unterschiedliche Arten betrieben werden. Neben Paketinstallationen und containerbasierten Deployments ist das klassische WAR-Deployment innerhalb eines Servlet-Containers wie Apache Tomcat eine bewährte Variante für produktive Umgebungen mit hohem Anspruch an Kontrolle und Anpassbarkeit.

Container- und Appliance-Lösungen ermöglichen zwar einen schnellen Einstieg, abstrahieren jedoch viele technische Details. Das klassische WAR-Deployment erfordert mehr Verständnis für:

  • Java
  • Tomcat
  • Datenbankanbindung
  • Reverse Proxy
  • TLS
  • Applikationsarchitektur

bietet dafür aber maximale Transparenz über die gesamte Umgebung.

Für produktive Installationen sollte grundsätzlich eine Long Term Support Version eingesetzt werden. Eine LTS-Version bildet die stabile Grundlage für:

  • Sicherheitsupdates
  • Wartung
  • Support
  • langfristige Betriebsfähigkeit

Organisationen, die offiziellen Support durch XWiki oder einen Partner in Anspruch nehmen möchten, benötigen zusätzlich eine gültige Subscription. Ohne aktive Subscription ist kein offizieller Support vorgesehen.

Für Partner ist diese Vorgabe verbindlich. Supportleistungen dürfen nur für Instanzen erbracht werden, die:

  • auf einer supportfähigen LTS-Version basieren
  • über eine gültige Subscription verfügen

Dadurch wird sichergestellt, dass produktive Systeme nicht ohne Wartungsgrundlage betrieben werden.

4. XWiki im Kontext moderner Kollaborationsplattformen

In vielen Organisationen wird XWiki nicht isoliert betrieben, sondern als Bestandteil einer größeren Kollaborations- und Projektmanagement-Landschaft eingesetzt.

Besonders in Kombination mit OpenProject entsteht eine leistungsfähige Open-Source-Alternative zu klassischen Atlassian-Umgebungen.

Dabei übernimmt:

  • XWiki → Wissensmanagement, Dokumentation und Kollaboration
  • OpenProject → Projektmanagement, Tickets, Roadmaps und Aufgabenverwaltung

Durch die Kombination beider Plattformen entsteht eine kontrollierbare und langfristig wartbare Umgebung für:

  • Projektmanagement
  • Wissensmanagement
  • technische Dokumentation
  • Team-Kollaboration

Gerade im Kontext digitaler Souveränität und europäischer IT-Strategien gewinnt dieser Ansatz zunehmend an Bedeutung.

5. Zielarchitektur

Die empfohlene Architektur trennt klar die einzelnen Komponenten und definiert eindeutige Verantwortlichkeiten.

XWiki selbst läuft innerhalb von Apache Tomcat und ist nicht direkt aus dem Netzwerk erreichbar. Der Zugriff erfolgt ausschließlich über einen vorgeschalteten Reverse Proxy.

bash
Client / Browser
      |
      | HTTPS
      v
Nginx Reverse Proxy
      |
      | HTTP lokal
      v
Apache Tomcat / XWiki
      |
      | JDBC
      v
PostgreSQL

Diese Struktur reduziert die Angriffsfläche und sorgt für eine klare Trennung der Aufgabenbereiche.

Während Nginx für:

  • TLS
  • Routing
  • Security Header
  • Request Handling

zuständig ist, übernimmt Tomcat ausschließlich die Ausführung der Anwendung. PostgreSQL bildet die persistente Datengrundlage.

Wichtige Prinzipien:

  • Tomcat nicht öffentlich erreichbar
  • Zugriff ausschließlich über Nginx mit TLS
  • Datenbank getrennt betreiben
  • klare Trennung von Web-, Applikations- und Datenbank-Schicht

6. Voraussetzungen

Für die Installation werden folgende Komponenten benötigt:

  • Java (empfohlen: OpenJDK 21)
  • Apache Tomcat
  • PostgreSQL
  • PostgreSQL JDBC-Treiber
  • Nginx
  • DNS-Eintrag für die spätere Instanz (z. B. wiki.example.com)

Zusätzlich sollte bereits vor der Installation entschieden werden, welche XWiki-Version eingesetzt wird. Für produktive Umgebungen ist ausschließlich eine aktuelle LTS-Version empfehlenswert.

7. Installation der Systempakete

Die Installation erfolgt abhängig von der jeweiligen Linux-Distribution. Ziel ist ein einheitlicher Aufbau über alle großen OS-Familien hinweg.

Debian-basierte Systeme

bash
apt update
apt upgrade -y
apt install -y openjdk-21-jdk postgresql postgresql-contrib nginx wget unzip
apt install -y tomcat10

Red Hat-basierte Systeme

bash
dnf update -y
dnf install -y java-21-openjdk postgresql-server postgresql nginx wget unzip tomcat


postgresql-setup --initdb
systemctl enable --now postgresql
systemctl enable --now tomcat

SUSE-basierte Systeme

bash
zypper refresh
zypper update -y
zypper install -y java-21-openjdk postgresql-server postgresql nginx wget unzip tomcat


systemctl enable --now postgresql
systemctl enable --now tomcat

8. PostgreSQL vorbereiten

Für XWiki wird eine eigene Datenbank sowie ein dedizierter Benutzer angelegt. Dadurch bleibt die Datenhaltung sauber getrennt und sicher konfiguriert.

bash
sudo -u postgres psql


sql
CREATE USER xwiki WITH ENCRYPTED PASSWORD 'CHANGE_ME';
CREATE DATABASE xwiki OWNER xwiki ENCODING 'UTF8' TEMPLATE template0;
GRANT ALL PRIVILEGES ON DATABASE xwiki TO xwiki;
\connect xwiki
GRANT ALL ON SCHEMA public TO xwiki;
\q

Das Passwort sollte entsprechend den internen Sicherheitsrichtlinien gewählt und nicht im Klartext dokumentiert werden.

9. XWiki WAR Deployment

XWiki wird als WAR-Datei heruntergeladen und in Tomcat bereitgestellt. Diese Variante bietet maximale Kontrolle über Version und Deployment.

Debian-basierte Systeme

bash
cd /tmp
wget https://maven.xwiki.org/releases/org/xwiki/platform/xwiki-platform-distribution-war/18.3.0/xwiki-platform-distribution-war-18.3.0.war


cp *.war /var/lib/tomcat10/webapps/ROOT.war
chown tomcat:tomcat /var/lib/tomcat10/webapps/ROOT.war
systemctl restart tomcat

Red Hat/SUSE-basierte Systeme

bash
cd /tmp
wget https://maven.xwiki.org/releases/org/xwiki/platform/xwiki-platform-distribution-war/18.3.0/xwiki-platform-distribution-war-18.3.0.war


cp *.war /var/lib/tomcat/webapps/ROOT.war
chown tomcat:tomcat /var/lib/tomcat/webapps/ROOT.war
systemctl restart tomcat

10. PostgreSQL JDBC-Treiber einbinden

Damit XWiki mit PostgreSQL kommunizieren kann, muss der passende JDBC-Treiber bereitgestellt werden.

Debian-basierte Systeme

bash
apt install -y libpostgresql-jdbc-java
cp /usr/share/java/postgresql.jar /var/lib/tomcat10/webapps/ROOT/WEB-INF/lib/

Red Hat-basierte Systeme

bash
dnf install -y postgresql-jdbc
cp /usr/share/java/postgresql*.jar /var/lib/tomcat/webapps/ROOT/WEB-INF/lib/postgresql.jar

SUSE-basierte Systeme

bash
zypper install -y postgresql-jdbc
cp /usr/share/java/postgresql*.jar /var/lib/tomcat/webapps/ROOT/WEB-INF/lib/postgresql.jar


11. Datenbank-Konfiguration in XWiki

Die Verbindung zur Datenbank wird in der Datei hibernate.cfg.xml definiert.

xml
<property name="hibernate.connection.url">jdbc:postgresql://127.0.0.1:5432/xwiki</property>
<property name="hibernate.connection.username">xwiki</property>
<property name="hibernate.connection.password">CHANGE_ME</property>
<property name="hibernate.connection.driver_class">org.postgresql.Driver</property>
<property name="hibernate.dialect">org.hibernate.dialect.PostgreSQLDialect</property>

Zusätzlich muss das PostgreSQL-Mapping aktiviert werden:

xml
<mapping resource="xwiki.postgresql.hbm.xml"/>

12. Tomcat absichern

Tomcat sollte ausschließlich lokal erreichbar sein. Dazu wird der Connector auf 127.0.0.1 gebunden.

xml
<Connector address="127.0.0.1" port="8080" protocol="HTTP/1.1"/>

Überprüfung:

bash
ss -tulpn | grep 8080

13. Nginx Reverse Proxy konfigurieren

Nginx übernimmt die externe Kommunikation und leitet Anfragen an Tomcat weiter.

bash
upstream backend {
  server 127.0.0.1:8080;
}


server {
  listen 80;
  server_name wiki.example.com;
  return 301 https://$host$request_uri;
}


server {
  listen 443 ssl http2;
  server_name wiki.example.com;


  ssl_certificate /etc/ssl/certs/wiki.crt;
  ssl_certificate_key /etc/ssl/private/wiki.key;


  location / {
    proxy_pass http://backend;


    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header X-Forwarded-For $remote_addr;
  }
}

14. TLS und Security Härtung

bash
ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;


add_header Strict-Transport-Security "max-age=31536000" always;
add_header X-Frame-Options SAMEORIGIN;
add_header X-Content-Type-Options nosniff;

Generierung der dhparams.pem

bash
openssl dhparam -out /etc/nginx/dhparam.pem 4096

15. Erstzugriff und Web-Setup

Nach erfolgreicher Installation erfolgt der Zugriff über:

https://wiki.example.com

Beim ersten Aufruf startet der Setup-Prozess. Dabei werden grundlegende Einstellungen vorgenommen und die Instanz initialisiert.

Typische Schritte:

  • Start des Setup-Wizards
  • Auswahl der Distribution
  • Einrichtung des Administrators
  • Abschluss der Installation

Screenshots:





16. Best Practices im produktiven Betrieb

Für stabile produktive Umgebungen haben sich folgende Grundsätze bewährt:

  • Einsatz einer aktuellen LTS-Version
  • Tomcat ausschließlich lokal betreiben
  • Zugriff nur über Nginx mit TLS
  • regelmäßige Datenbank-Backups
  • Trennung von Konfiguration und Daten
  • Updates vorab testen
  • zentrale Log-Auswertung
  • Monitoring der JVM und Datenbank

17. Fazit

Die klassische Installation von XWiki als WAR-Deployment bietet eine hohe Transparenz und Kontrolle über die gesamte Umgebung.

Durch die klare Trennung von:

  • Reverse Proxy
  • Applikationsserver
  • Datenbank

entsteht eine stabile und wartbare Architektur, die sich flexibel an unterschiedliche Anforderungen anpassen lässt.

In Kombination mit OpenProject kann zusätzlich eine leistungsfähige Open-Source-Alternative zu Atlassian Confluence und Jira aufgebaut werden, die langfristig kontrollierbar, transparent und unabhängig betrieben werden kann.

18. Ausblick

Im nächsten Beitrag wird gezeigt, wie sich diese Installation vollständig mit Ansible automatisieren lässt. Dabei werden Deployment, Konfiguration, TLS-Härtung und Updates reproduzierbar und standardisiert umgesetzt.


Ebenso ein Container/Kubernetes Deployment.