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

Resource Minimum Recommended CPU 2 cores 4+ cores RAM 4 GB 16 GB Storage 20 GB 100 GB

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

Enter fullscreen mode Exit fullscreen mode

Installing Dependencies

Install and configure Apache Tomcat

Tomcat serves as our servlet container for hosting XWiki:

~$ sudo dnf install tomcat -y

Enter fullscreen mode Exit fullscreen mode

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

Enter fullscreen mode Exit fullscreen mode

or

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

Enter fullscreen mode Exit fullscreen mode

Configure Firewall

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

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

Enter fullscreen mode Exit fullscreen mode

Verify it’s open:

~$ sudo firewall-cmd --list-all

Enter fullscreen mode Exit fullscreen mode

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

Enter fullscreen mode Exit fullscreen mode

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"

Enter fullscreen mode Exit fullscreen mode

Memory Explanation:

Setting Value Purpose -Xms 1080MB Initial heap size (prevents startup allocation spikes) -Xmx 1600MB Maximum heap size (prevents runaway memory consumption) –add-opens N/A Required for Java 17+ compatibility with certain libraries

Set ownership and test:

~$ sudo chown tomcat:tomcat /var/lib/tomcat/bin/setenv.sh
~$ sudo systemctl enable --now tomcat
~$ sudo systemctl status tomcat

Enter fullscreen mode Exit fullscreen mode

Test from another machine by visiting <a href="http://:8080″ target=”_blank” rel=”noopener noreferrer”>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

Enter fullscreen mode Exit fullscreen mode

Database Configuration (PostgreSQL)

Install PostgreSQL

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

Enter fullscreen mode Exit fullscreen mode

Initialize and Start PostgreSQL

~$ sudo postgresql-setup --initdb
~$ sudo systemctl enable --now postgresql
~$ sudo systemctl status postgresql

Enter fullscreen mode Exit fullscreen mode

Create XWiki User and Database

Switch to the postgres user:

~$ sudo su postgres
bash-5.2$ psql

Enter fullscreen mode Exit fullscreen mode

Then run these SQL commands:

CREATE USER xwiki PASSWORD 'xwikipassword';
CREATE DATABASE xwiki WITH OWNER=xwiki;
GRANT ALL ON SCHEMA public TO xwiki;
q 

Enter fullscreen mode Exit fullscreen mode

⚠️ 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;"

Enter fullscreen mode Exit fullscreen mode

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

Enter fullscreen mode Exit fullscreen mode

Replace these lines:

# OLD (insecure)
host    all             all             127.0.0.1/32            ident
host    all             all             ::1/128                 ident

Enter fullscreen mode Exit fullscreen mode

by

# NEW (secure)
host    all             all             127.0.0.1/32            scram-sha-256
host    all             all             ::1/128                 scram-sha-256

Enter fullscreen mode Exit fullscreen mode

Reload PostgreSQL to apply changes:

~$ sudo systemctl reload postgresql

Enter fullscreen mode Exit fullscreen mode

Verify Database Connection:

~$ psql postgresql://xwiki:xwikipassword@localhost
xwiki=> l  # Should list databases including 'xwiki'
xwiki=> q  # Exit psql
~$

Enter fullscreen mode Exit fullscreen mode

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
~$ 

Enter fullscreen mode Exit fullscreen mode

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/

Enter fullscreen mode Exit fullscreen mode

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

Enter fullscreen mode Exit fullscreen mode

Configure Hibernate for PostgreSQL

Edit the Hibernate configuration:

~$ cd /var/lib/tomcat/webapps/xwiki/WEB-INF
~$ sudo nano hibernate.cfg.xml

Enter fullscreen mode Exit fullscreen mode

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

Enter fullscreen mode Exit fullscreen mode

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

Enter fullscreen mode Exit fullscreen mode

⚠️ 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

Enter fullscreen mode Exit fullscreen mode

Edit the properties file:

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

Enter fullscreen mode Exit fullscreen mode

Uncomment and verify this line:

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

Enter fullscreen mode Exit fullscreen mode

Starting the Application

~$ sudo systemctl start tomcat

Enter fullscreen mode Exit fullscreen mode

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

Enter fullscreen mode Exit fullscreen mode

Look for messages like XWiki context has been initialized successfully.

XWiki Configuration Wizard

Running the Configuration Wizard

Navigate to your server: <a href="http://:8080/xwiki” target=”_blank” rel=”noopener noreferrer”>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

Action Priority Command/File Change default PostgreSQL password High psql ALTER USER command Update Tomcat manager passwords High tomcat-users.xml Enable HTTPS via reverse proxy High nginx/Apache configuration Restrict database access Medium pg_hba.conf network rules Regular backups High XWiki GUI + cron jobs + pg_dump

Performance Tuning

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

# Edit setenv.sh
CATALINA_OPTS="-Xmx2048m ..."  # Increase if needed

Enter fullscreen mode Exit fullscreen mode

Enable query caching in xwiki.properties:

cache.default.maxSize = 5000

Enter fullscreen mode Exit fullscreen mode

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

Enter fullscreen mode Exit fullscreen mode

File Data:

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

Enter fullscreen mode Exit fullscreen mode

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:

Factor On-Premises Cloud Data Control Full Limited by provider Customization Unlimited Restricted Cost (Long-term) Lower Subscription-based Offline Access Yes Requires internet Integration Direct system access API-only

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