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 or . You should see the Tomcat welcome page. Once confirmed, stop the service — we'll restart after XWiki deployment:
  
  
  
  
  
  
  

  CODE Kopieren

  ~$ sudo systemctl stop tomcat
  
  

  
  
  
  
  
  
  
  

  
  
  
  Database Configuration (PostgreSQL)
  

  
  
  

  
  
  
  Install PostgreSQL
  

  
  
  
  
  
  
  

  CODE Kopieren

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

  
  
  
  
  
  
  
  

  Initialize and Start PostgreSQL
  
  

  
  
  
  
  

  CODE Kopieren

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

  
  
  
  
  
  
  
  

  
  
  
  Create XWiki User and Database
  

  
  
  

  Switch to the postgres user:
  
  

  
  
  
  
  

  CODE Kopieren

  ~$ sudo su postgres
  
  bash-5.2$ psql
  
  

  
  
  
  
  
  
  
  

  Then run these SQL commands:
  
  

  
  
  
  
  

  CODE Kopieren

  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:
  
  

  
  
  
  
  

  CODE Kopieren

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

  
  
  
  
  

  CODE Kopieren

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

  
  
  
  
  
  
  
  

  Replace these lines:
  
  

  
  
  
  
  

  CODE Kopieren

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

  
  
  
  
  
  
  
  

  by
  
  

  
  
  
  
  

  CODE Kopieren

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

  
  
  
  
  

  CODE Kopieren

  ~$ sudo systemctl reload postgresql
  
  

  
  
  
  
  
  
  
  

  Verify Database Connection:
  
  

  
  
  
  
  

  CODE Kopieren

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

  Place them in a download directory:
  
  

  
  
  
  
  

  CODE Kopieren

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

  
  
  
  
  

  CODE Kopieren

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

  
  
  
  
  
  
  

  CODE Kopieren

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

  
  
  
  
  

  CODE Kopieren

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

  
  
  
  
  
  
  
  

  Find and comment out the default database section:
  
  

  
  
  
  
  

  CODE Kopieren

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

  
  
  
  
  

  CODE Kopieren

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

  
  
  
  
  

  CODE Kopieren

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

  
  
  
  
  
  
  
  

  
  
  
  Edit the properties file:
  

  
  
  
  
  
  
  

  CODE Kopieren

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

  
  
  
  
  
  
  
  

  Uncomment and verify this line:
  
  

  
  
  
  
  

  CODE Kopieren

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

  
  
  
  
  
  
  
  

  
  
  
  Starting the Application
  

  
  
  
  
  
  
  

  CODE Kopieren

  ~$ sudo systemctl start tomcat
  
  

  
  
  
  
  
  
  
  

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

  
  
  
  
  

  CODE Kopieren

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

  
  
  

  
  
  
  Wizard Steps
  

  
  
  
  
  

  Press Register and Login.

  
  
  
  
  

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

  
  
  
  
  

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

  
  
  
  
  

  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:
  
  

  
  
  
  
  

  CODE Kopieren

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

  
  
  
  
  
  
  
  

  
  
  
  Enable query caching in xwiki.properties:
  

  
  
  
  
  
  
  

  CODE Kopieren

  cache.default.maxSize = 5000
  
  

  
  
  
  
  
  
  
  

  
  
  
  Backup Strategy
  

  
  
  

  
  
  
  Using XWiki GUI
  

  
  
  

  Go to Administer Wiki:

  
  
  
  
  

  And select Export:

  
  
  
  
  

  
  
  
  Database:
  

  
  
  
  
  
  
  

  CODE Kopieren

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

  
  
  
  
  
  
  
  

  
  
  
  File Data:
  

  
  
  
  
  
  
  

  CODE Kopieren

  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:

  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  

  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
  

  
  
  
  
  
  
  
  • Administrator Guide
  
  
  Vollständiger Original-Bericht

  Ausführliche Details, Code-Beispiele & Hersteller-Stellungnahme auf dev.to.

  ↗ Original-Artikel auf dev.to lesen