Latest News And Updates - Rad Web Hosting Blog

Learn 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: Resource Minimum Recommended CPU 2 vCPU 4 vCPU RAM 4 GB 8 GB Storage 30 GB SSD 60+ GB SSD Operating system Debian 13 Debian 13 Public IP One IPv4 address Static IPv4 Domain Required for SSL wiki.example.com 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. How to Deploy XWiki on Debian VPS To deploy XWiki on Debian VPS, follow the steps outlined below: 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. 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 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. 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. If SSH operates on a custom port, allow that port before enabling UFW: sudo ufw allow 2211/tcp 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. Install XWiki with PostgreSQL Run: sudo apt install xwiki-xjetty-pgsql The installer may display several dbconfig-common prompts. Recommended answers: Configure the database with dbconfig-common? Select Yes. Database type or connection method Choose the local PostgreSQL or Unix-socket option when offered. PostgreSQL administrative account Accept the local/default administrative connection unless you already maintain a separate PostgreSQL server. 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. 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. 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 'ava' If multiple Java versions are installed, inspect the active default: readlink -f "$(command -v java)" 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. 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 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/ 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/ Complete the Distribution Wizard The first browser request may take several minutes because XWiki initializes its database, search index, and extension system. XWiki Distribution Wizard The Distribution Wizard will open automatically. Proceed through these steps: Select Continue. Create the first administrator account. Select XWiki Standard Flavor. Install the recommended flavor and extensions. Allow the installer to resolve dependencies. Finish the initialization process. Sign in with the administrator account. The initial administrator account is especially sensitive. Use: 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. 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 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. 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. Locate the Important Files The XWiki package stores its primary files in these locations: 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 Back Up XWiki A complete XWiki backup must include: PostgreSQL database /etc/xwiki /var/lib/xwiki/data Nginx configuration 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 \ --formatcustom \ --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 Upgrade XWiki Safely Before upgrading: Create and verify a backup. Read the release notes for every version being crossed. Confirm Java and servlet-container requirements. 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. Troubleshooting XWiki does not start Inspect the service: 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 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. Conclusion You now know how to deploy XWiki on Debian VPS.

Rad Web Hosting Blog

Recent Posts

Nothing Found

My Feed at https://radwebhosting.com

Services

Categories

Recent Posts

Save on VPS Hosting!

We’re Social!

Rad Web Hosting Blog