XWiki Installation: Docker, Nginx und PostgreSQL

·

Eine Testinstanz von XWiki ist schnell aufgesetzt. Doch welche Aspekte sind entscheidend für einen stabilen und produktiven Dauerbetrieb?

Dieser Artikel bietet einen kompakten Leitfaden für die Installation von XWiki unter Ubuntu 26.04, mit Docker, Nginx und PostgreSQL. Um den Artikel prägnant zu halten, wird nicht auf Basiskonfigurationen eingegangen (beispielsweise: DNS, Domain, SSH-Zugriff, Firewall, Datensicherung, Paketupdates etc.).

Docker Container

XWiki unterstützt eine Vielzahl von Installationsmethoden. Wir verwenden gerne die Docker-Variante, da aus unserer Erfahrung der Betrieb (insbesondere Updates) am einfachsten von der Hand geht.

Webserver: Nginx

In den meisten Szenarien macht es Sinn einen HTTP Proxy vorzuschalten. Wir benutzen hierfür Nginx oder den Apache HTTP Server. In diesem Artikel beschreiben wir die Konfiguration von Nginx.

PostgreSQL Datenbank

Nahezu jede relationale Datenbank (z. B. Oracle, MySQL, MariaDB etc.) kann für XWiki verwendet werden. Wir setzen in diesem Artikel auf PostgreSQL.

Pakete

Bevor wir loslegen, aktualisieren wir das System und installieren einige grundlegende Tools:

# Paketlisten aktualisieren und System updaten
apt update && apt upgrade -y

# Grundlegende Tools installieren
apt install ca-certificates curl gnupg git net-tools unzip plocate apt-utils -y

Docker

Das offizielle Installationsskript von Docker ist der schnellste Weg:

# Docker installieren
curl -fsSL https://get.docker.com | sh

# Überprüfen, ob Docker erfolgreich installiert worden ist
apt install docker-compose-plugin

# Docker Dienst aktivieren & starten
systemctl enable docker
systemctl start docker

Nginx

Als HTTP Proxy verwenden wir Nginx sowie certbot für SSL-Zertifikate, die von Let’s Encrypt ausgestellt werden:

# Nginx & certbot installieren
sudo apt install nginx certbot python3-certbot-nginx

# Installation überprüfen
nginx -v

Anpassung der Headergrößen (relevant für XWiki)

# Nginx Konfiguration editieren
vi /etc/nginx/nginx.conf
http {
        proxy_headers_hash_max_size 1024;
        proxy_headers_hash_bucket_size 128;

Certbot

Zuerst legen wir eine ganz einfache Nginx Konfiguration an, damit der Webserver erreichbar ist.

Anschließend aktivieren wir diese Konfiguration und versuchen über Let’s Encrypt ein SSL Zertifikat zu beziehen.
Dies funktioniert nur, wenn die Domain-/DNS-Konfiguration richtig vorgenommen wurde.

# Start Konfiguration anlegen
vi /etc/nginx/sites-available/wiki.domain.de

# Konfiguration bekannt machen
ln -s /etc/nginx/sites-available/wiki.domain.de /etc/nginx/sites-enabled/wiki.domain.de

# Default Konfiguration entfernen
unlink /etc/nginx/sites-enabled/default


# Nginx Konfiguration neu laden
systemctl reload nginx

server {
    listen 80;

    server_name wiki.domain.de;

    root /var/www/html;
    index index.html;
}

Jetzt beziehen wir ein Zertifikat woraufhin sich die eben angelegte Konfigurationsdatei verändern sollte.

# Zertifikat anfragen
certbot --nginx -d wiki.domain.de

# Prüfen ob der Erneuerungstask hinterlegt ist
systemctl list-timers

# Zertifikatsverlängerung testen
certbot renew --dry-run

Nach der erfolgreichen Ausführung sollte die Datei /etc/nginx/sites-available/wiki.domain.de wie folgt aussehen:

server {

    server_name wiki.domain.de;

    root /var/www/html;
    index index.html;

    listen 443 ssl; # managed by Certbot
    ssl_certificate /etc/letsencrypt/live/wiki.domain.de/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/wiki.domain.de/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

}
server {
    if ($host = wiki.domain.de) {
        return 301 https://$host$request_uri;
    } # managed by Certbot


    listen 80;

    server_name wiki.domain.de;
    return 404; # managed by Certbot

Nach Abschluss der Vorarbeiten kann nun die finale Proxy-Konfiguration für XWiki implementiert werden.

Dazu die Datei /etc/nginx/sites-available/wiki.domain.de wie folgt erweitern:

server {

    server_name wiki.domain.de;

    #root /var/www/html;
    #index index.html;

    listen 443 ssl; # managed by Certbot
    ssl_certificate /etc/letsencrypt/live/wiki.domain.de/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/wiki.domain.de/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot
    
    access_log /var/log/nginx/wiki.domain.de.access.log;
    error_log  /var/log/nginx/wiki.domain.de.error.log warn;

    client_max_body_size 10M;
    client_body_buffer_size 128k;

    add_header Strict-Transport-Security "max-age=63072000" always;
    add_header X-Robots-Tag "noindex, nofollow, nosnippet, noarchive" always;
    add_header Content-Security-Policy "upgrade-insecure-requests" always;

    # --- OIDC-Callback IMMER durchlassen ---
    location = /oidc/authenticator/callback {
      proxy_pass http://127.0.0.1:8080;
      proxy_set_header Host              $host;
      proxy_set_header X-Real-IP         $remote_addr;
      proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Host  $host;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_set_header X-Forwarded-Port  443;
    } 

    # --- XWiki-Login-Starter durchlassen (sonst Redirect-Loop) ---
    location = /bin/login/XWiki/XWikiLogin {
      proxy_pass http://127.0.0.1:8080;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Host $host;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_set_header X-Forwarded-Port 443;
    }

    # --- optionale statische Pfade ohne Session zulassen (schneller) ---
    location ~ ^/(resources|skins|webjars|assets)/ {
      proxy_pass http://127.0.0.1:8080;
      proxy_set_header Host $host;
    }
 
    # --- Haupt-Location: ohne Session => Redirect zum Login-Starter ---
    location / {
      # Prüft, ob ein JSESSIONID-Cookie gesetzt ist (Groß/Klein egal).
      if ($http_cookie !~* "(^|;\\s*)JSESSIONID=") {
        return 302 /bin/login/XWiki/XWikiLogin?loginLink=1&xredirect=$request_uri;
      }

      proxy_http_version 1.1;
      proxy_set_header Host              $host;
      proxy_set_header X-Real-IP         $remote_addr;
      proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Host  $host;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_set_header X-Forwarded-Port  443;
      proxy_set_header Upgrade           $http_upgrade;
      proxy_set_header Connection        "upgrade";
      proxy_read_timeout 120s;
      proxy_send_timeout 120s;

      proxy_pass http://127.0.0.1:8080;
    }   
}

server {
    if ($host = wiki.domain.de) {
        return 301 https://$host$request_uri;
    } # managed by Certbot

    listen 80;

    server_name wiki.domain.de;
    return 404; # managed by Certbot
}

XWiki

Jetzt können wir uns der eigentlichen XWiki Installation widmen. Dazu sind ein paar Grundlagen notwendig:

# Technischen User & Gruppe anlegen
groupadd xwiki
useradd -m -s /bin/bash -g xwiki xwiki


# Verzeichnisstruktur anlegen & Rechte anpassen
mkdir -p /var/apphome/xwiki/xwiki-data
mkdir -p /var/apphome/xwiki/postgres-data
chown -R xwiki:xwiki /var/apphome/xwiki
chown -R 999:999 /var/apphome/xwiki/postgres-data

Der letzte Befehl ist notwendig da PostgreSQL im offiziellen Docker Container mit der UID 999 läuft.
Werden die Rechte nicht entsprechend angepasst, kann der Container nicht in das Verzeichnis schreiben.

Im XWiki-Docker Repository auf Github finden sich die Basis Docker-Compose Files.
Wir benutzen das File für XWiki 17 (aktuelle LTS Version) in Kombination mit PostgreSQL als Datenbank.
Zusätzlich wird ein .env File benötigt, hier werden die notwendigen Variablen definiert.

# Docker-Compose & .env File anlegen
cd /var/apphome/xwiki/
wget -O docker-compose.yml https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/17/postgres-tomcat/docker-compose.yml

wget -O .env https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/17/postgres-tomcat/.env

Docker Compose

Das im vorherigen Schritt heruntergeladene Docker Compose File wie folgt anpassen:

# Docker-Compose File anpassen
vi /var/apphome/xwiki/docker-compose.yml

# ---------------------------------------------------------------------------
# See the NOTICE file distributed with this work for additional
# information regarding copyright ownership.
#
# This is free software; you can redistribute it and/or modify it
# under the terms of the GNU Lesser General Public License as
# published by the Free Software Foundation; either version 2.1 of
# the License, or (at your option) any later version.
#
# This software is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this software; if not, write to the Free
# Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
# 02110-1301 USA, or see the FSF site: http://www.fsf.org.
# ---------------------------------------------------------------------------
networks:
  bridge:
    driver: bridge
services:
  # The container that runs XWiki in Tomcat, with the appropriate JDBC driver (for postgres).
  web:
    image: "xwiki:${XWIKI_VERSION}-postgres-tomcat"
    container_name: xwiki-postgres-tomcat-web
    depends_on:
      - db
    ports:
      - "8080:8080"
    # Default values defined in .env file.
    # The DB_USER/DB_PASSWORD/DB_DATABASE/DB_HOST variables are used in the hibernate.cfg.xml file.
    restart: always
    environment:
      - XWIKI_VERSION=${XWIKI_VERSION}
      - DB_USER=${DB_USER}
      - DB_PASSWORD=${DB_PASSWORD}
      - DB_DATABASE=${DB_DATABASE}
      - DB_HOST=xwiki-postgres-db
      - CATALINA_OPTS=-Xms2048m -Xmx4096m
      - TZ=Europe/Berlin
    # Provide a name instead of an auto-generated id for xwiki data (the permanent directory in included in it)
    # configured in the Dockerfile, to make it simpler to identify in 'docker volume ls'.
    volumes:
      - /var/apphome/xwiki/xwiki-data:/usr/local/xwiki
    networks:
      - bridge
  # The container that runs the database (postgres)
  db:
    image: "postgres:18"
    container_name: xwiki-postgres-db
    restart: always
    environment:
      - POSTGRES_ROOT_PASSWORD=${POSTGRES_ROOT_PASSWORD}
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_USER=${DB_USER}
      - POSTGRES_DB=${DB_DATABASE}
      - POSTGRES_INITDB_ARGS=--encoding=UTF8 --locale-provider=builtin --locale=C.UTF-8
    volumes:
      - /var/apphome/xwiki/postgres-data:/var/lib/postgresql
    networks:
      - bridge
.env File

Das im vorherigen Schritt heruntergeladene .env File wie folgt anpassen, dabei natürlich selbst gewählte Passwörter vergeben und die aktuelle XWiki LTS Version eintragen:

# Docker-Compose File anpassen
vi /var/apphome/xwiki/.env

# Default environment values
XWIKI_VERSION=17.10.7
DB_USER=xwiki
DB_PASSWORD=PASSSWORRT11
DB_DATABASE=xwiki
POSTGRES_ROOT_PASSWORD=PASSSWOORRTT22
Erster Start

Nach dem ersten Start sollten zwei relevante Konfigurationsfiles in das XWiki Data Verzeichnis kopiert werden.
Das dient dazu, dass die Files im Filesystem des Hosts verwaltet werden können, da das Data Verzeichnis ein gemountetes Host Verzeichnis ist.
Zum Start des Containers werden sie automatisiert aus dem XWiki Data Ordner in den Tomcat des Containers kopiert.

# In Anwendungsverzeichnis wechseln
cd /var/apphome/xwiki/


# Container starten
docker compose up -d


# xwiki.cfg/properties in das XWiki Data Verzeichnis kopieren
docker exec -it xwiki-postgres-tomcat-web /bin/bash

cp -a /usr/local/tomcat/webapps/ROOT/WEB-INF/xwiki.properties /usr/local/xwiki/data/
cp -a /usr/local/tomcat/webapps/ROOT/WEB-INF/xwiki.cfg /usr/local/xwiki/data/


# Container neustarten
docker compose down

docker compose up -d

Jetzt sollte das Wiki unter https://wiki.domain.de aufrufbar sein. 🥳

Konfiguration

Bevor das Wiki einsatzbereit ist, muss im Browser eine Grundkonfiguration erfolgen. Dabei wird ein Admin-User angelegt, ein Flavor (ähnlich Themes/Templates) installiert sowie grundlegende Seiten angelegt.

Für einen produktiven Einsatz, vielleicht sogar öffentlich erreichbar aus dem Internet, sollten noch weiterführende Konfigurationen vorgenommen werden. Diese Einstellungen sind nicht Teil dieses Artikels.

Bei Fragen zu dem beschriebenen Vorgehen oder anderen Themen rund um XWiki, helfen wir gerne weiter.

Was können wir für Sie tun?

Egal, welche Unterstützung Sie zu XWiki benötigen, wir helfen Ihnen gerne. Schicken Sie uns einfach eine formlose Anfrage per E-Mail oder rufen Sie uns an: +49-841-1380-1644