Complete Guide: Setting Up XWiki 17 on Premises

This guide walks through deploying XWiki 17.10.8 on Red Hat Enterprise Linux 10.2 with Apache Tomcat and PostgreSQL. Total setup time: ~45 minutes. Requires minimum 8GB RAM and 4 vCPUs for acceptable performance.

If you're looking to deploy a self-hosted wiki solution with enterprise-grade features, XWiki is an excellent choice. Unlike some alternatives, it offers powerful permission management, structured data, and extensibility through extensions. However, the on-premises setup can be intimidating due to multiple moving parts.

This guide details setting up XWiki 17 on Red Hat Linux Server 10.2 with 16GB RAM and 4 vCPUs. I initially validated these steps in a Mac-hosted VM before deploying them to my production environment on a Dell OptiPlex 7050 Micro.

What You'll Need

Hardware Requirements

Note: During my initial setup on a 2GB RAM old laptop, XWiki was functional but painfully slow. The jump to 16GB made a night-and-day difference in responsiveness.

Software Stack

• Operating System: Red Hat Enterprise Linux 10.2 or Fedora Server


• Servlet Container: Apache Tomcat 10.1.x (Jetty is also supported)


• Database: PostgreSQL 16.x


• Java: OpenJDK 21


• XWiki Platform: 17.10.8 WAR package

Comments:

• As Operating System, you can use other Linux Distributions, including Ubuntu, Windows Server and Docker Engine.


• As Servlet Container, Jetty is also a supported option.


• Other supported databases are HyperSQL, MariaDB, MySQL, or Oracle.


• For more information, review XWiki prerequisites.

Time Investment

• Installation: ~30 minutes


• Configuration: ~15 minutes


• Testing: ~10 minutes

Preparation Steps

Install Your Base OS

For this guide, I'm using Red Hat Enterprise Linux, but most steps work equally well on Fedora Server if you don't have RHEL subscriptions.

Download from Red Hat Developer Program or Fedora Server.

Once installed, register (if using RHEL), update, and reboot:

~$ sudo subscription-manager register --username <username> --password <password>

~$ sudo dnf upgrade -y

~$ reboot

Installing Dependencies

Install and configure Apache Tomcat

Tomcat serves as our servlet container for hosting XWiki:

~$ sudo dnf install tomcat -y

This command pulls in Java 21 along with necessary dependencies automatically. Review the installation output to confirm java-21-openjdk-headless was included.

Architecture Note:

Package names vary by architecture:

• x86_64: java-21-openjdk-headless.x86_64


• aarch64: java-21-openjdk-headless.aarch64

If it seems to be missing:

~$ sudo dnf install java-21-openjdk-headless.x86_64 -y

or

~$ sudo dnf install java-21-openjdk-headless.aarch64 -y

Configure Firewall

Allow HTTP traffic on port 8080 (Tomcat's default):

~$ sudo firewall-cmd --permanent --add-port=8080/tcp

~$ sudo firewall-cmd --reload

Verify it's open:

~$ sudo firewall-cmd --list-all

Configure Tomcat Memory Settings

By default, Tomcat won't allocate enough memory for XWiki to perform well. Create a custom setenv.sh file:

~$ sudo mkdir -p /var/lib/tomcat/bin

~$ sudo chown tomcat:tomcat -R /var/lib/tomcat

~$ sudo nano /var/lib/tomcat/bin/setenv.sh

Add this configuration:

#!/bin/sh

export JAVA_OPTS="${JAVA_OPTS} -Djava.awt.headless=true"

export CATALINA_OPTS="-server -Xms1080m -Xmx1600m -Dfile.encoding=utf-8 \

-Djava.awt.headless=true \

--add-opens java.base/java.lang=ALL-UNNAMED \

--add-opens java.base/java.io=ALL-UNNAMED \

--add-opens java.base/java.util=ALL-UNNAMED \

--add-opens java.base/java.util.concurrent=ALL-UNNAMED"

Memory Explanation:

Set ownership and test:

~$ sudo chown tomcat:tomcat /var/lib/tomcat/bin/setenv.sh

~$ sudo systemctl enable --now tomcat

~$ sudo systemctl status tomcat

Test from another machine by visiting http://your-server-name:8080. You should see the Tomcat welcome page. Once confirmed, stop the service — we'll restart after XWiki deployment:

~$ sudo systemctl stop tomcat

Database Configuration (PostgreSQL)

Install PostgreSQL

~$ sudo dnf install postgresql-server postgresql-contrib -y

Initialize and Start PostgreSQL

~$ sudo postgresql-setup --initdb

~$ sudo systemctl enable --now postgresql

~$ sudo systemctl status postgresql

Create XWiki User and Database

Switch to the postgres user:

~$ sudo su postgres

bash-5.2$ psql

Then run these SQL commands:

CREATE USER xwiki PASSWORD 'xwikipassword';

CREATE DATABASE xwiki WITH OWNER=xwiki;

GRANT ALL ON SCHEMA public TO xwiki;

\q 

⚠️ Security Warning: Replace 'xwikipassword' with a strong, unique password. Never use default credentials in production. Consider using environment variables or secret management tools like HashiCorp Vault for sensitive data.

Configure PostgreSQL Authentication

Find the authentication config file:

~$ sudo su postgres

bash-5.2$ psql -c "SHOW hba_file;"

By default, the file and location is /var/lib/pgsql/data/pg_hba.conf

Edit the pg_hba.conf file to change authentication method:

~$ sudo nano /var/lib/pgsql/data/pg_hba.conf

Replace these lines:

# OLD (insecure)

host    all             all             127.0.0.1/32            ident

host    all             all             ::1/128                 ident

by

# NEW (secure)

host    all             all             127.0.0.1/32            scram-sha-256

host    all             all             ::1/128                 scram-sha-256

Reload PostgreSQL to apply changes:

~$ sudo systemctl reload postgresql

Verify Database Connection:

~$ psql postgresql://xwiki:xwikipassword@localhost

xwiki=> \l  # Should list databases including 'xwiki'

xwiki=> \q  # Exit psql

~$

Deploying XWiki

Download Required Files

Get these two files from official sources:

• XWiki WAR Package: Production Installation → Select "WAR Package for Servlet Container"


• PostgreSQL JDBC Driver: Official Downloads
  

Place them in a download directory:

~$ mkdir ~/downloads

~$ cd ~/downloads

# wget the links here from browser or CLI

~$ ls downloads/

postgresql-42.7.11.jar  xwiki-platform-distribution-war-17.10.8.jar

~$ 

Deploy the WAR Package

Copy and extract the XWiki WAR:

~$ sudo cp ~/downloads/xwiki-platform-distribution-war-17.10.8.jar /var/lib/tomcat/webapps/

~$ cd /var/lib/tomcat/webapps

~$ sudo unzip xwiki-platform-distribution-war-17.10.8.jar

~$ sudo mkdir xwiki

~$ sudo mv META-INF redirect resources skins templates WEB-INF xwiki/

~$ sudo rm xwiki-platform-distribution-war-17.10.8.jar

~$ sudo chown -R tomcat:tomcat xwiki/

Common Pitfall: If you get an error about moving files into themselves, ensure you're not inside the extracted directory when creating the target folder.

Add PostgreSQL JDBC Driver

~$ cd /var/lib/tomcat/webapps/xwiki/WEB-INF/lib

~$ sudo cp ~/downloads/postgresql-42.7.11.jar .

~$ sudo chown tomcat:tomcat *.jar

Configure Hibernate for PostgreSQL

Edit the Hibernate configuration:

~$ cd /var/lib/tomcat/webapps/xwiki/WEB-INF

~$ sudo nano hibernate.cfg.xml

Find and comment out the default database section:

    <!--

    <property name="hibernate.connection.url">jdbc:hsqldb:file:${environment.permanentDirectory}/database/xwiki_db;shutdown=true</property>

    <property name="hibernate.connection.username">sa</property>

    <property name="hibernate.connection.password"></property>

    <property name="hibernate.connection.driver_class">org.hsqldb.jdbcDriver</property>

    -->

Find and uncomment the PostgreSQL section:

    <!-- PostgreSQL configuration.

         Uncomment if you want to use PostgreSQL and comment out other database configurations.

         Notes:

           - "hibernate.jdbc.use_streams_for_binary" needs to be set to "false",

             see https://community.jboss.org/wiki/HibernateCoreMigrationGuide36

           - "xwiki.virtual_mode" can be set to either "schema" or "database". Note that currently the database mode

             doesn't support database creation (see https://jira.xwiki.org/browse/XWIKI-8753)

           - if you want the main wiki database to be different than "xwiki" (or "public" in schema mode)

             you will also have to set the property xwiki.db in xwiki.cfg file

    -->



    <property name="hibernate.connection.url">jdbc:postgresql://localhost:5432/xwiki</property>

    <property name="hibernate.connection.username">xwiki</property>

    <property name="hibernate.connection.password">**xwikipassword**</property>

    <property name="hibernate.connection.driver_class">org.postgresql.Driver</property>

    <property name="hibernate.jdbc.use_streams_for_binary">false</property>

    <property name="xwiki.virtual_mode">schema</property>



    <property name="hibernate.connection.charSet">UTF-8</property>

    <property name="hibernate.connection.useUnicode">true</property>

    <property name="hibernate.connection.characterEncoding">utf8</property>



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

    <mapping resource="feeds.hbm.xml"/>

    <mapping resource="instance.hbm.xml"/>

    <mapping resource="notification-filter-preferences.hbm.xml"/>

    <mapping resource="mailsender.hbm.xml"/>





    <!-- Oracle configuration.

...

⚠️ Password Reminder: Update the password value to match what you set earlier!

Configure Permanent Directory

Create a dedicated directory for XWiki data:

~$ sudo mkdir -p /var/lib/xwiki/data

~$ sudo chown -R tomcat:tomcat /var/lib/xwiki

Edit the properties file:

~$ nano /var/lib/tomcat/webapps/xwiki/WEB-INF/xwiki.properties

Uncomment and verify this line:

environment.permanentDirectory = /var/lib/xwiki/data/

Starting the Application

~$ sudo systemctl start tomcat

Wait 3-5 minutes for Tomcat to fully initialize XWiki (it compiles resources on first boot). Monitor logs:

~$ sudo tail -f /var/log/tomcat/catalina.out

Look for messages like XWiki context has been initialized successfully.

XWiki Configuration Wizard

Running the Configuration Wizard

Navigate to your server: http://your-server-name:8080/xwiki.

You'll see an initialization banner briefly, then the wizard will appear.

Wizard Steps

Press Continue to begin

Create Administrator Account: Set a strong admin password (save this securely!).

Press Register and Login.

Press Continue

Install Standard Flavor: Select "XWiki Standard Flavor" from the dropdown—this includes useful built-in applications

Press Install this flavor: Wait 2-5 minutes depending on hardware

Press Install

Once you see it has been Installed, Press Continue to completion.

After finalization, press Continue and you'll be redirected to your XWiki home page with example documentation.

Your XWiki server is ready!

Post-Installation Checklist

Security Hardening

Performance Tuning

With 16GB RAM, you may want to increase XWiki's maximum heap:

# Edit setenv.sh

CATALINA_OPTS="-Xmx2048m ..."  # Increase if needed

Enable query caching in xwiki.properties:

cache.default.maxSize = 5000

Backup Strategy

Using XWiki GUI

Go to Administer Wiki:

Select Content:

And select Export:

You can select what pages to export/backup.

Database:

pg_dump -U xwiki xwiki > xwiki_backup_$(date +%Y%m%d).sql

File Data:

tar czf xwiki_files_$(date +%Y%m%d).tar.gz /var/lib/xwiki/data/

Schedule these as cron jobs for automated backups.

Troubleshooting Common Issues

Issue: XWiki Won't Load After Startup

Symptoms: Browser shows blank page or timeout at /xwiki

Solutions:

• Check logs: tail -f /var/log/tomcat/catalina.out
  


• Verify database connection is active


• Ensure hibernate.cfg.xml has correct credentials


• Restart Tomcat completely

Issue: Slow Page Loading

Symptoms: Pages take 5+ seconds to load

Solutions:

• Increase JVM heap in setenv.sh


• Check available RAM with free -h


• Disable unnecessary extensions in XWiki admin panel


• Consider upgrading to SSD storage

Issue: Database Connection Error

Symptoms: "Cannot connect to database" during wizard

Solutions:

• Verify PostgreSQL is running: sudo systemctl status postgresql
  


• Test connectivity: psql -U xwiki -d xwiki
  


• Check pg_hba.conf has scram-sha-256 authentication


• Ensure firewall allows localhost PostgreSQL connections (port 5432)

Why On-Premises Over Cloud?

You might wonder why choose self-hosted instead of XWiki Cloud. Here are compelling reasons:

For organizations handling sensitive data or requiring deep integration, on-premises deployment provides the flexibility you need.

Final Thoughts

Setting up XWiki on-premises involves coordinating several components, but once configured, you have a powerful, self-contained knowledge management platform. The setup I've outlined balances security, performance, and maintainability.

Got questions or encountered different errors? Drop a comment below — I'm happy to help troubleshoot!

Further Resources

• Installing XWiki .war package manually


• Release Notes for XWiki 17.10.8


• Administrator Guide