DEV Community

Ana Villar
Ana Villar

Posted on

Complete Guide: Setting Up XWiki 17 on Premises

#linux #xwiki #tutorial #devops

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

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: http://your-server-name:8080/xwiki.

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

XWiki initialization banner

Wizard Steps

Distribution wizard

Press Continue to begin

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

Create Admin User

Press Register and Login.

User created

Press Continue

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

Standard Flavor

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

Flavor deployment

Press Install

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

Deployment completed

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

XWiki Home Page

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:

Administer Wiki

Select Content:

Administer Options

And select Export:

Option Export

You can select what pages to export/backup.

Export

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

Top comments (0)