Practical guide to architecture, WAR deployment, PostgreSQL integration, Nginx reverse proxy, and TLS hardening

1. Introduction

XWiki is a powerful open-source platform for knowledge management, technical documentation, and collaborative work. Thanks to its modular architecture, extensive permission management, and integrated extension mechanism, XWiki is suitable for both internal documentation platforms and complex enterprise environments.

In the context of digital sovereignty, controllable and long-term maintainable platforms are becoming increasingly important. Many organizations are questioning existing dependencies on proprietary cloud solutions and are looking for alternatives that can be operated fully under their own control.

XWiki positions itself as a possible open-source alternative to Atlassian Confluence. In combination with OpenProject, it can also form a comprehensive platform for project management, documentation, and collaboration. While XWiki handles structured knowledge management, OpenProject covers task management, ticketing, roadmaps, and project control.

In productive operation, functionality alone is not enough. A clean technical architecture is equally important, especially if the system must remain maintainable, secure, and supportable over the long term. An XWiki instance consists of several components that need to work together correctly: Java as the runtime environment, Apache Tomcat as the servlet container, PostgreSQL as the database, and Nginx as the reverse proxy for external access.

This article describes a classic installation of XWiki as a WAR deployment. The individual components are explained deliberately so that it remains clear what each component does and why certain decisions make sense for productive environments.

The installation is considered across the three major Linux OS families:

  • Debian-based systems
  • Red Hat-based systems
  • SUSE-based systems

Special focus is placed on:

  • a supportable LTS installation
  • a local Tomcat backend
  • clean PostgreSQL integration
  • a hardened Nginx configuration with TLS
  • clear separation between web, application, and database layers

The later automation of these steps with Ansible will be covered in a follow-up article.

2. Goal of This Article

The goal of this article is not just to get XWiki running. Instead, it aims to provide a transparent foundation for productive installations.

Especially with WAR deployment, it is important to understand which components are involved and what responsibility each one has.

  • Tomcat provides the application
  • PostgreSQL stores content and metadata
  • Nginx forms the secure access layer to the outside

This clear separation simplifies:

  • troubleshooting
  • updates
  • security hardening
  • monitoring
  • later automation

This article is therefore intended for:

  • administrators
  • service providers
  • technical decision-makers
  • operators of productive Linux infrastructures

who do not only want to test XWiki, but operate it reliably over the long term.

3. Productive Operating Models and Supportability

XWiki can be operated in different ways. In addition to package-based installations and container-based deployments, classic WAR deployment inside a servlet container such as Apache Tomcat is a proven option for productive environments that require a high degree of control and customization.

Container and appliance solutions allow for a quick start, but they also abstract away many technical details. Classic WAR deployment requires more understanding of:

  • Java
  • Tomcat
  • database integration
  • reverse proxying
  • TLS
  • application architecture

but offers maximum transparency across the entire environment.

For productive installations, a Long Term Support version should generally be used. An LTS version provides a stable foundation for:

  • security updates
  • maintenance
  • support
  • long-term operability

Organizations that want to use official support from XWiki or a partner also require a valid subscription. Without an active subscription, official support is not provided.

For partners, this requirement is binding. Support services may only be provided for instances that:

  • are based on a supportable LTS version
  • have a valid subscription

This ensures that productive systems are not operated without a proper maintenance basis.

4. XWiki in the Context of Modern Collaboration Platforms

In many organizations, XWiki is not operated in isolation, but as part of a larger collaboration and project management landscape.

Especially in combination with OpenProject, it can form a powerful open-source alternative to classic Atlassian environments.

The responsibilities are typically split as follows:

  • XWiki → knowledge management, documentation, and collaboration
  • OpenProject → project management, tickets, roadmaps, and task management

Together, both platforms create a controllable and long-term maintainable environment for:

  • project management
  • knowledge management
  • technical documentation
  • team collaboration

This approach is becoming increasingly relevant in the context of digital sovereignty and European IT strategies.

5. Target Architecture

The recommended architecture clearly separates the individual components and defines clear responsibilities.

XWiki itself runs inside Apache Tomcat and is not directly reachable from the network. Access is provided exclusively through a reverse proxy in front of it.

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

This structure reduces the attack surface and ensures a clear separation of responsibilities.

While Nginx is responsible for:

  • TLS
  • routing
  • security headers
  • request handling

Tomcat is responsible only for executing the application. PostgreSQL provides the persistent data foundation.

Important principles:

  • Tomcat is not publicly reachable
  • access only via Nginx with TLS
  • database operated separately
  • clear separation of web, application, and database layers

6. Requirements

The following components are required for the installation:

  • Java, recommended: OpenJDK 21
  • Apache Tomcat
  • PostgreSQL
  • PostgreSQL JDBC driver
  • Nginx
  • DNS record for the later instance, for example wiki.example.com

Before starting the installation, the XWiki version should also be selected. For productive environments, only a current LTS version is recommended.

7. Installing System Packages

The installation depends on the Linux distribution used. The goal is to create a consistent setup across all major OS families.

Debian-Based Systems

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

Red Hat-Based Systems

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-Based Systems

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. Preparing PostgreSQL

A dedicated database and user are created for XWiki. This keeps data storage cleanly separated and securely configured.

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;
\q

The password should be chosen according to internal security policies and should not be documented in plain text.

9. XWiki WAR Deployment

XWiki is downloaded as a WAR file and deployed into Tomcat. This method provides maximum control over version and deployment.

Debian-Based Systems

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-Based Systems

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. Adding the PostgreSQL JDBC Driver

To allow XWiki to communicate with PostgreSQL, the matching JDBC driver must be provided.

Debian-Based Systems

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

Red Hat-Based Systems

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

SUSE-Based Systems

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


11. Database Configuration in XWiki

The database connection is defined in the hibernate.cfg.xml file.

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>

The PostgreSQL mapping must also be enabled:

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

12. Hardening Tomcat

Tomcat should only be reachable locally. For this, the connector is bound to 127.0.0.1.

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

Verification:

bash
ss -tulpn | grep 8080

13. Configuring the Nginx Reverse Proxy

Nginx handles external communication and forwards requests to Tomcat.

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 and Security Hardening

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;

Generate dhparams.pem:

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

15. First Access and Web Setup

After the installation has been completed successfully, XWiki can be accessed via:

https://wiki.example.com

On the first visit, the setup process starts. During this process, the basic settings are configured and the instance is initialized.

Typical steps:

  • start of the setup wizard
  • selection of the distribution
  • creation of the administrator
  • completion of the installation

Screenshots:





16. Best Practices for Productive Operation

For stable productive environments, the following principles have proven useful:

  • use a current LTS version
  • run Tomcat locally only
  • provide access only via Nginx with TLS
  • perform regular database backups
  • separate configuration and data
  • test updates in advance
  • use centralized log analysis
  • monitor the JVM and database

17. Conclusion

The classic installation of XWiki as a WAR deployment provides a high degree of transparency and control over the entire environment.

The clear separation of:

  • reverse proxy
  • application server
  • database

creates a stable and maintainable architecture that can be adapted flexibly to different requirements.

In combination with OpenProject, it is also possible to build a powerful open-source alternative to Atlassian Confluence and Jira that can be operated transparently, independently, and under long-term control.

18. Outlook

In the next article, we will show how this installation can be fully automated with Ansible. Deployment, configuration, TLS hardening, and updates can then be implemented in a reproducible and standardized way.

A container or Kubernetes deployment is also a possible next step.