🚀 How to Deploy XWiki on Debian VPS

This article provides a guide demonstrating how to deploy XWiki on Debian VPS.

What is XWiki?

XWiki is a free, open-source enterprise wiki and application development platform written in Java. Unlike traditional wikis that only let you store text and documents, XWiki is a “second-generation” wiki. It allows you to build small, structured web applications—like task trackers, inventories, or approval forms—directly inside your wiki pages using structured data and scripts.

Key Features

• Structured Data: Add fields, numbers, dates, and relationships to pages to turn them into data records.
• Advanced Permissions: Manage fine-grained user access rights and security groups.
• WYSIWYG Editor: Edit pages easily with a rich visual text editor or use a robust wiki syntax.
• Extensibility: Install over 900 extensions, macros, and skins from the community repository.
• Open Source: Licensed under the GNU LGPL, meaning the core software is free to download, use, and self-host. Professional cloud hosting and enterprise support are offered by XWiki SAS.

Common Use Cases

• Knowledge Bases: Centralize internal company documentation and guides.
• Collaborative Intranets: Build team workspaces, policies, and internal communication hubs.
• Extranets and Communities: Create shared portals for external partners or public projects.
• Custom Business Apps: Track project workflows and specialized data without needing an external database tool.

This guide deploys XWiki as a production-ready internal knowledge base using:

• Debian 13
• XWiki’s official stable APT repository
• XWiki’s packaged Jetty application server
• PostgreSQL
• Nginx reverse proxy
• Let’s Encrypt SSL
• UFW firewall

XWiki 18 requires Java 21, so Debian 13 is the simplest supported foundation. The XWiki package manager automatically installs the required Java runtime, database components, and application server dependencies.

Prerequisites

Recommended starting resources:

XWiki can run on 4 GB RAM for a small organization, but 8 GB provides more comfortable capacity for indexing, extensions, document previews, and concurrent users.

Create a DNS record before proceeding:

Type: A
Name: wiki
Value: YOUR_SERVER_IP
TTL: 300

Replace wiki.example.com throughout this guide with your actual hostname.

See Also: Understanding Vendor Lock-In: Impacts, Examples, and Avoidance Strategies

How to Deploy XWiki on Debian VPS

To deploy XWiki on Debian VPS, follow the steps outlined below:

1. Connect to the Server

   Connect as root:

   ssh root@YOUR_SERVER_IP
   

   Alternatively, connect as a sudo-enabled user:

   ssh username@YOUR_SERVER_IP
   

   Commands in this guide use sudo. If logged in as root, you may omit it.

2. Configure the Hostname and Timezone

   Set the server hostname:

   sudo hostnamectl set-hostname wiki.example.com
   

   Add it to /etc/hosts:

   sudo nano /etc/hosts
   

   Ensure the file contains an entry similar to:

   127.0.0.1 localhost
   127.0.1.1 wiki.example.com wiki
   

   Set the appropriate timezone:

   sudo timedatectl set-timezone America/Chicago
   

   Verify:

   hostnamectl
   timedatectl
   

3. Update Debian

   Update the package index and installed packages:

   sudo apt update
   sudo apt full-upgrade -y
   

   Install the utilities needed by this guide:

   sudo apt install -y \
       wget \
       curl \
       ca-certificates \
       gnupg \
       ufw \
       nginx \
       certbot \
       python3-certbot-nginx
   

   If a new kernel was installed, reboot:

   sudo reboot
   

   Reconnect after the VPS comes back online.

4. Configure the Firewall

   Allow SSH before enabling UFW:

   sudo ufw allow OpenSSH
   

   Allow HTTP and HTTPS:

   sudo ufw allow 'Nginx Full'
   

   Enable the firewall:

   sudo ufw enable
   

   Check its status:

   sudo ufw status verbose
   

   The expected public ports are:

   • TCP 22 for SSH
   • TCP 80 for HTTP
   • TCP 443 for HTTPS

   Do not expose PostgreSQL port 5432 or XWiki’s backend port 8080 publicly.

   See Also: How to Install Dokploy on Ubuntu VPS

   If SSH operates on a custom port, allow that port before enabling UFW:

   sudo ufw allow 2211/tcp
   

5. Add the Official XWiki Repository

   Download the XWiki signing key:

   sudo wget https://maven.xwiki.org/xwiki-keyring.gpg \
       -O /usr/share/keyrings/xwiki-keyring.gpg
   

   Add the stable XWiki repository:

   sudo wget https://maven.xwiki.org/stable/xwiki-stable.list \
       -O /etc/apt/sources.list.d/xwiki-stable.list
   

   Update APT:

   sudo apt update
   

   Check the available XWiki packages:

   apt search '^xwiki-'
   

   The official repository offers several combinations of database and application server. This guide uses:

   xwiki-xjetty-pgsql
   

   That package combines XWiki’s customized Jetty distribution with PostgreSQL integration. It avoids tying the deployment to the particular Tomcat version shipped by Debian.

6. Install XWiki with PostgreSQL

   Run:

   sudo apt install xwiki-xjetty-pgsql
   

   The installer may display several dbconfig-common prompts.

   Recommended answers:

   1. Configure the database with dbconfig-common?
      Select Yes.
   2. Database type or connection method
      Choose the local PostgreSQL or Unix-socket option when offered.
   3. PostgreSQL administrative account
      Accept the local/default administrative connection unless you already maintain a separate PostgreSQL server.
   4. Application database password
      Generate and enter a strong password, or allow the installer to generate one.

   The installer should:

   • Install PostgreSQL
   • Create the XWiki database
   • Create the XWiki database user
   • Install the required Java runtime
   • Install the XWiki Jetty service
   • Configure the database connection
   • Start XWiki

   XWiki’s current stable releases require Java 21.

7. Verify the Services

   Check PostgreSQL:

   sudo systemctl status postgresql --no-pager
   

   Check XWiki:

   sudo systemctl status xwiki --no-pager
   

   Enable both services at startup:

   sudo systemctl enable postgresql
   sudo systemctl enable xwiki
   

   Check which process is listening on port 8080:

   sudo ss -lntp | grep ':8080'
   

   Test XWiki locally:

   curl -I http://127.0.0.1:8080/xwiki/
   

   A successful response may be 200 OK or a redirect such as 302 Found.

   XWiki may need several minutes for its first startup. If the test initially fails, watch the service log:

   sudo journalctl -u xwiki -f
   

   Press Ctrl+C to exit.

8. Confirm the Java Version

   Run:

   java -version
   

   For XWiki 18, the result should report Java 21 or newer.

   See the Java process used by XWiki:

   ps -eo pid,user,cmd | grep '[j]ava'
   

   If multiple Java versions are installed, inspect the active default:

   readlink -f "$(command -v java)"
   

9. Configure XWiki’s Memory Allocation

   First inspect the packaged service definition:

   sudo systemctl cat xwiki
   

   Also inspect its Java configuration:

   sudo grep -R "Xmx\|JAVA_OPTS" \
       /etc/xwiki \
       /etc/default/xwiki \
       /lib/systemd/system/xwiki.service \
       /usr/lib/systemd/system/xwiki.service \
       2>/dev/null
   

   XWiki’s package layout can change between releases, so modify the existing JAVA_OPTS or memory setting identified by these commands instead of creating a competing definition blindly.

   See Also: Ultimate Guide to VPS Security Hardening

   A reasonable small-production configuration for an 8 GB VPS is:

   -Xms1g -Xmx4g
   

   For a 4 GB VPS, use approximately:

   -Xms512m -Xmx2g
   

   Do not assign all VPS memory to Java. PostgreSQL, Nginx, the operating system, and filesystem caching also need RAM.

   After changing the applicable configuration:

   sudo systemctl daemon-reload
   sudo systemctl restart xwiki
   

   Verify:

   sudo systemctl status xwiki --no-pager
   

10. Configure Nginx as the Reverse Proxy

    Create an Nginx virtual host:

    sudo nano /etc/nginx/sites-available/xwiki
    

    Enter:

    map $http_upgrade $connection_upgrade {
        default upgrade;
        ''      close;
    }
    
    server {
        listen 80;
        listen [::]:80;
    
        server_name wiki.example.com;
    
        client_max_body_size 100M;
    
        location / {
            return 301 /xwiki/;
        }
    
        location /xwiki/ {
            proxy_pass http://127.0.0.1:8080/xwiki/;
            proxy_http_version 1.1;
    
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Host $host;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_set_header X-Forwarded-Port $server_port;
    
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection $connection_upgrade;
    
            proxy_connect_timeout 60s;
            proxy_send_timeout 600s;
            proxy_read_timeout 600s;
    
            proxy_buffering off;
        }
    }
    

    The client_max_body_size value controls the maximum request size accepted by Nginx. Increase it if users need to upload larger attachments.

    Enable the site:

    sudo ln -s /etc/nginx/sites-available/xwiki \
        /etc/nginx/sites-enabled/xwiki
    

    Remove the default Nginx site:

    sudo unlink /etc/nginx/sites-enabled/default
    

    Validate the configuration:

    sudo nginx -t
    

    If successful, reload Nginx:

    sudo systemctl reload nginx
    

    Test:

    curl -I http://wiki.example.com/xwiki/
    

11. Obtain a Let’s Encrypt Certificate

    Make sure the domain resolves to the VPS:

    getent ahostsv4 wiki.example.com
    

    Then request the certificate:

    sudo certbot --nginx \
        -d wiki.example.com \
        --redirect
    

    Certbot will:

    • Request the certificate
    • Add the certificate paths to Nginx
    • Configure HTTP-to-HTTPS redirection
    • Reload Nginx

    Test automatic renewal:

    sudo certbot renew --dry-run
    

    Check the renewal timer:

    systemctl status certbot.timer --no-pager
    

    Open:

    https://wiki.example.com/xwiki/
    

12. Complete the Distribution Wizard

    The first browser request may take several minutes because XWiki initializes its database, search index, and extension system.

    

    The Distribution Wizard will open automatically.

    Proceed through these steps:

    1. Select Continue.
    2. Create the first administrator account.
    3. Select XWiki Standard Flavor.
    4. Install the recommended flavor and extensions.
    5. Allow the installer to resolve dependencies.
    6. Finish the initialization process.
    7. Sign in with the administrator account.

    The initial administrator account is especially sensitive. Use:

    See Also: 🛠️ How to Install and Configure ListMonk on Ubuntu VPS

    • A unique username
    • A long, randomly generated password
    • A password manager
    • Multifactor authentication if an appropriate extension or external identity provider is configured

    Do not leave the initial installation unfinished on a publicly reachable server.

13. Configure the Public URL

    After signing in, open:

    Administration → Configuration
    

    Confirm that XWiki generates URLs using:

    https://wiki.example.com/xwiki/
    

    If it creates HTTP URLs or redirects to port 8080, first verify that Nginx is passing:

    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Port $server_port;
    

    Then inspect the XWiki configuration:

    sudo nano /etc/xwiki/xwiki.cfg
    

    and:

    sudo nano /etc/xwiki/xwiki.properties
    

    Avoid adding arbitrary URL settings unless the forwarded headers do not solve the issue. Restart XWiki after changing either file:

    sudo systemctl restart xwiki
    

14. Prevent Direct Access to Port 8080

    Check UFW:

    sudo ufw status numbered
    

    There should be no rule allowing port 8080.

    Test from another system:

    curl -I http://YOUR_SERVER_IP:8080/xwiki/
    

    That external connection should fail.

    The local test should continue to work:

    curl -I http://127.0.0.1:8080/xwiki/
    

    For stronger isolation, configure Jetty to listen only on 127.0.0.1 after identifying the connector settings under /etc/xwiki. Do this carefully, because the exact Jetty configuration structure can vary across XWiki releases.

15. Configure XWiki for an Internal Organization

    Recommended initial administrative tasks include:

    Create groups

    Navigate to:

    Administration → Users & Rights → Groups
    

    Create role-based groups such as:

    • XWikiAllEmployees
    • XWikiContentEditors
    • XWikiDepartmentManagers
    • XWikiAdministrators

    Assign rights to groups rather than individual users wherever possible.

    Restrict anonymous access

    Navigate to:

    Administration → Users & Rights → Rights
    

    Remove view, edit, comment, and registration rights from unauthenticated users if the wiki should be private.

    Test this in a private browser window before assuming the restriction works.

    Disable open registration

    If accounts will be created by administrators or an identity provider, disable public account registration under the user and registration settings.

    Create a content structure

    A practical initial hierarchy might include:

    • Company Handbook
    • Standard Operating Procedures
    • Departments
    • IT Resources
    • Human Resources
    • Training
    • Policies
    • Forms and Templates
    • Archived Documentation

    Use page permissions sparingly. A simple group-based permission model is easier to audit than many page-specific exceptions.

16. Locate the Important Files

    The XWiki package stores its primary files in these locations:

    See Also: 🚀 Deploy OpenStatus on Debian VPS (5 Minute Quick-Start Guide)

    Purpose	Location
    XWiki configuration	/etc/xwiki/
    Permanent XWiki data	/var/lib/xwiki/data/
    Application files	/usr/lib/xwiki/
    XWiki service logs	systemd journal
    PostgreSQL configuration	/etc/postgresql/
    PostgreSQL data	/var/lib/postgresql/
    Nginx site configuration	/etc/nginx/sites-available/xwiki
    Let’s Encrypt certificates	/etc/letsencrypt/

    View the XWiki log:

    sudo journalctl -u xwiki -n 200 --no-pager
    

    Follow it live:

    sudo journalctl -u xwiki -f
    

    View Nginx errors:

    sudo tail -f /var/log/nginx/error.log
    

17. Back Up XWiki

    A complete XWiki backup must include:

    1. PostgreSQL database
    2. /etc/xwiki
    3. /var/lib/xwiki/data
    4. Nginx configuration
    5. Let’s Encrypt configuration, if the certificate is not otherwise recoverable

    A page export or XAR export alone is not a complete system backup. XWiki’s backup guidance explicitly calls for preserving the database, configuration, and permanent data.

    Create a manual backup

    Create a protected backup directory:

    sudo install -d -m 700 /var/backups/xwiki
    

    Use a timestamp:

    BACKUP_DATE="$(date +%F-%H%M%S)"
    

    Dump the PostgreSQL database:

    sudo -u postgres pg_dump \
        --format=custom \
        --file="/var/backups/xwiki/xwiki-${BACKUP_DATE}.dump" \
        xwiki
    

    Back up the filesystem data:

    sudo tar -C / \
        -czf "/var/backups/xwiki/xwiki-files-${BACKUP_DATE}.tar.gz" \
        etc/xwiki \
        var/lib/xwiki/data \
        etc/nginx/sites-available/xwiki \
        etc/letsencrypt
    

    List the resulting files:

    sudo ls -lh /var/backups/xwiki
    

    Copy these backups to storage outside the VPS. A backup stored only on the same VPS does not protect against disk failure, filesystem corruption, or loss of the server.

    Verify the database name

    If pg_dump reports that the xwiki database does not exist, list the databases:

    sudo -u postgres psql -l
    

    Use the database name shown in XWiki’s Hibernate configuration:

    sudo grep -n "connection.url" /etc/xwiki/hibernate.cfg.xml
    

18. Upgrade XWiki Safely

    Before upgrading:

    1. Create and verify a backup.
    2. Read the release notes for every version being crossed.
    3. Confirm Java and servlet-container requirements.
    4. Schedule a maintenance window.

    Check installed XWiki packages:

    dpkg -l | grep '^ii.*xwiki'
    

    Check available versions:

    apt-cache policy xwiki-xjetty-pgsql
    

    Update the package index:

    sudo apt update
    

    Upgrade only the XWiki package and its required dependencies:

    sudo apt install xwiki-xjetty-pgsql
    

    Restart XWiki:

    sudo systemctl restart xwiki
    

    Watch the logs:

    sudo journalctl -u xwiki -f
    

    Then sign in through the browser. If prompted, complete the Distribution Wizard’s flavor upgrade.

    XWiki’s official upgrade sequence calls for backing up first, reviewing intervening release notes, upgrading the packages, restarting the servlet container, and completing the browser-based flavor upgrade. For more information, visit the official Debian-package upgrade procedure.

19. Troubleshooting

    • XWiki does not start

      Inspect the service:

      See Also: Launch a FreeBSD 15 VPS Server

      sudo systemctl status xwiki --no-pager -l
      sudo journalctl -u xwiki -n 300 --no-pager
      

      Common causes include:

      • Insufficient memory
      • Incorrect Java version
      • PostgreSQL authentication failure
      • Invalid configuration changes
      • Port 8080 already in use
      • Incomplete package configuration

      Check the port:

      sudo ss -lntp | grep ':8080'
      

      Resume an interrupted package setup:

      sudo dpkg --configure -a
      sudo apt --fix-broken install
      

    • Nginx returns 502 Bad Gateway

      Confirm that XWiki is running:

      sudo systemctl status xwiki --no-pager
      

      Test the backend directly:

      curl -I http://127.0.0.1:8080/xwiki/
      

      If this local request fails, the problem is XWiki or Jetty—not Nginx.

    • Installation remains on a loading screen

      Watch the log:

      sudo journalctl -u xwiki -f
      

      First startup and flavor installation can take several minutes. Also verify available memory and disk space:

      free -h
      df -h
      

    • Out-of-memory errors

      Look for Java memory failures:

      sudo journalctl -u xwiki --no-pager | grep -iE \
          'outofmemory|java heap|killed process|oom'
      

      Check kernel OOM events:

      sudo journalctl -k --no-pager | grep -iE \
          'out of memory|oom|killed process'
      

      Increase XWiki’s Java heap only if the VPS has sufficient unused RAM.

    • Uploads fail with HTTP 413

      Increase this Nginx setting:

      client_max_body_size 100M;
      

      Then validate and reload:

      sudo nginx -t
      sudo systemctl reload nginx
      

      XWiki’s own attachment-size configuration may also need to be increased if Nginx accepts the request but XWiki rejects it.

    • PostgreSQL is unavailable

      Check its service:

      sudo systemctl status postgresql --no-pager
      

      Check database connectivity:

      sudo -u postgres psql -d xwiki -c 'SELECT 1;'
      

      Review recent PostgreSQL messages:

      sudo journalctl -u postgresql -n 200 --no-pager
      

20. Final Deployment Checklist

    Before putting the wiki into production, confirm:

    • DNS resolves to the correct VPS
    • HTTPS works without certificate warnings
    • HTTP redirects to HTTPS
    • Port 8080 is not publicly accessible
    • Anonymous users cannot view private material
    • Public registration is disabled if unnecessary
    • The administrator account uses a unique password
    • XWiki and PostgreSQL start after reboot
    • Java heap allocation fits the VPS
    • Off-server backups are scheduled
    • A restore procedure has been tested
    • Debian and XWiki security updates are applied regularly
    • Group-based permissions are documented
    • Monitoring is configured for HTTPS, disk space, memory, PostgreSQL, and the XWiki service

    Finally, perform a controlled reboot:

    sudo reboot
    

    After reconnecting, verify:

    sudo systemctl is-active postgresql
    sudo systemctl is-active xwiki
    sudo systemctl is-active nginx
    curl -I https://wiki.example.com/xwiki/
    

    All three services should report active, and the HTTPS request should return a successful response or expected redirect.

See Also: Automate Secure SSH Login to Remote Servers for Instant and Effortless Connectivity

Conclusion

You now know how to deploy XWiki on Debian VPS.