Installation using Debian/Ubuntu (.DEB) packages

Last modified by Thomas Mortagne on 2025/02/14

This distribution allows installing XWiki and every component needed for a production instance automatically.

This method works for all Debian-based linux distribution. Feel free to use the User Forum to report issues, or discuss about it.

Warning

Before XWiki 17, a critical dependency of the XWiki Tomcat Debian packages was tomcat9. Unfortunately Debian decided to remove the tomcat9 package to keep only tomcat10 starting with Debian 12 (bookworm) and Ubuntu 24.04. The current alternatives are:

APT Configuration

First, you have to configure your package manager in order to use XWiki's repository. This can be done simply, using this command:

sudo wget https://maven.xwiki.org/xwiki-keyring.gpg -O /usr/share/keyrings/xwiki-keyring.gpg
sudo wget "https://maven.xwiki.org/stable/xwiki-stable.list" -O /etc/apt/sources.list.d/xwiki-stable.list
Information

Note that there are several repositories you can choose (as alternatives to the stable one you have in the previous example):

Now you can update the packages database to read the data from this repository.

sudo apt-get update

Now you can make a little search to see what this repo offers.

apt-cache search xwiki
  • Common packages not tied to any application server or database
    • xwiki-common - XWiki, you can install this if you want to take care yourself of the database and application server
    • xwiki-mariadb-common - XWiki MariaDB common package, you can install this if you want to take care yourself of the application server
    • xwiki-mysql-common - XWiki MySQL common package, you can install this if you want to take care yourself of the application server
    • xwiki-pgsql-common - XWiki PostgreSQL common package, you can install this if you want to take care yourself of the application server
  • Packages based on a customized Jetty packaged for XWiki
    • xwiki-xjetty-common - XWiki Jetty common package, you can install this if you want to take care yourself of the database link
    • xwiki-xjetty-mariadb - XWiki Jetty/MariaDB based package
    • xwiki-xjetty-mysql - XWiki Jetty/MySQL based package
    • xwiki-xjetty-pgsql - XWiki Jetty/PostgreSQL
  • Packages based on the standard Tomcat package
    • xwiki-tomcat9-common - XWiki Tomcat 9 common package, you can install this if you want to take care yourself of the database link
    • xwiki-tomcat10-common - XWiki Tomcat 10 common package, you can install this if you want to take care yourself of the database link
    • xwiki-tomcat9-mariadb - XWiki Tomcat 9/MariaDB based package
    • xwiki-tomcat10-mariadb - XWiki Tomcat 10/MariaDB based package
    • xwiki-tomcat9-mysql - XWiki Tomcat 9/MySQL based package
    • xwiki-tomcat10-mysql - XWiki Tomcat 10/MySQL based package
    • xwiki-tomcat9-pgsql - XWiki Tomcat 9/PostgreSQL
    • xwiki-tomcat10-pgsql - XWiki Tomcat 10/PostgreSQL
  • Not really XWiki itself but Solr cores needed when you want to use a standalone Solr instance with XWiki
    • xwiki-solr9-all - An entry point package with dependencies on all the Solr 9 cores required to setup a standalone version compatible with XWiki Standard
    • xwiki-solr9-search - A pre configured Solr 9 core for the XWiki search feature
    • xwiki-solr9-events - A pre configured Solr 9 core for the XWiki events/notifications storage
    • xwiki-solr9-ratings - A pre configured Solr 9 core for the XWiki rating storage
    • xwiki-solr9-extension_index - A pre configured Solr 9 core for the XWiki extensions index

Plus legacy packages from older versions of XWiki like xwiki-enterprise-* packages or for unsupported versions of Tomcat.

Information

According to selection, package manager will install all necessary dependencies (application server, database, Java runtime). If you haven't installed these packages before, package manager can ask additional info from you.

Warning

  On Ubuntu you will need universe repository to install Tomcat packages. It's generally enabled by default.

Complete Installation

Warning

Most Debian distributions provide a Tomcat package with a pretty low Memory setting by default (128MB) and this need to be increased for XWiki to fully work. See Tomcat Memory section for more details.

Using MariaDB

Warning

Note that XWiki requires at least MariaDB 10.2.

Xjetty:

sudo apt install xwiki-xjetty-mariadb

Tomcat 10:

sudo apt install xwiki-tomcat10-mariadb

Tomcat 9:

sudo apt install xwiki-tomcat9-mariadb

During the installation you may get some questions from DBconfig, which is in charge of the configuration of XWiki with the MariaDB database. Don't confuse it with the MariaDB root password prompt that asks you for a root password (which is intented for the superuser). If you haven't already installed any MariaDB databases and you are not familiar with it you should let DBconfig handle this.

Afterwards DBconfig asks you for the MariaDB root password for the "xwiki" MariaDB user. This user will be used to connect to MariaDB from the XWiki application. You should choose the password wisely but you don't have to pay a lot of attention to it after that because DBconfig internally configures XWiki to start up with these credentials.

Warning

The password should not contain any special characters, otherwise XWiki will fail to start. See https://jira.xwiki.org/browse/XWIKI-14406

The installation ends with the start of the XWiki or Tomcat daemon which is also setup to start automatically from boot.

Using MySQL

Warning

Note that XWiki requires at least MySQL 5.7. It's not recommended to use this package if your "MySQL" server is in fact MariaDB, see the MariaDB section.

Xjetty:

sudo apt install xwiki-xjetty-mysql

Tomcat 10:

sudo apt install xwiki-tomcat10-mysql

Tomcat 9:

sudo apt install xwiki-tomcat9-mysql

Everything else is similar to what is described in the the MariaDB section.

Using PostgreSQL

It's as simple as the MySQL installation, you only need to choose the right virtual package.

Xjetty:

sudo apt install xwiki-xjetty-pgsql

Tomcat 10:

sudo apt install xwiki-tomcat10-pgsql

Tomcat 9:

sudo apt install xwiki-tomcat9-pgsql

Everything else is similar to what is described in the the MariaDB section.

Starting up XWiki for the first time...

After you've made sure to update the memory settings (see below), you can now point your favorite browser to the following URL to use your wiki: http://localhost:8080/xwiki

Warning

Note that your wiki is absolutely empty, like a WAR installation. Distribution Wizard will take care of the rest.

Performance

XWiki

You can find various various generic advices and troubleshooting related to XWiki.

Tomcat

You can find various generic advices and troubleshooting related to Tomcat.

Java Version

Make sure Tomcat is executed with the right Java version.

This is usually indicated in the file /etc/default/tomcat10 (or /etc/default/tomcat9 for Tomcat 9, etc).

Memory

The default Tomcat memory setup is too low for XWiki's needs.

You can change it in the file /etc/default/tomcat10 (or /etc/default/tomcat9 for Tomcat 10, etc).

Modify the property JAVA_OPTS. For example:

JAVA_OPTS="-Djava.awt.headless=true -Xmx1024m"

You should check the Memory settings we recommend.

Concluding Step

At this point your wiki is empty, i.e it doesn't contain any wiki page. Since applications in XWiki are done in wiki pages so you also don't need any application available (e.g. Blog, User Directory, User Profiles, etc). In addition, your wiki doesn't contain any user.

Thus the final step is to fill your Wiki with some initial content (i.e. wiki pages).

This is the job of the Distribution Wizard which automatically starts when you are browsing your new XWiki instance for the first time.

The default distribution is a fully configured wiki that you can use as a starting point for creating your own wiki content. It provides the following:

Installing without internet connection

XIP Package

A XIP package is available. It contains an offline extension repository with all the extensions making the Standard Flavor.

This is actually a zip file containing the required XWiki extensions for both the main wiki and subwikis, in the same format as the one of the local extensions repository. It allows the Distribution Wizard to find the extensions locally instead of getting them online and is thus suited for offline installations of XWiki.

  • download it (use the exact same version of the XIP package as the version of XWiki you have)
  • Unzip it (rename it to .zip if your zip tool does not recognize it) in the folder <permanentdirectory>/extension/repository (if you get complains about already existing files don't overwrite them)
  • Make sure the user running XWiki has the permissions to write to these unzipped files
  • Restart XWiki if it was running
  • Resume standard installation, this time it will find the flavor locally
Information

XWiki doesn't offer XIP packages for Contrib Extensions. However it's possible to generate these XIPs.

Other methods

Several options:

Extension Repositories

XWiki performs some checks at startup and even at runtime and tries to connects to remote Extension repositories. This will not cause any problem if you're offline but you'll get some error logs. You may want to disable Extension repositories by editing your xwiki.properties config file and adding the following empty property (make sure that this is the only property defined with the name):

extension.repositories=

Upgrading

Update the packages index

sudo apt update

Upgrade the packages

sudo apt upgrade

This will upgrade all packages, not just XWiki. If you want to avoid all the other packages and only update XWiki, you can use sudo apt install xwiki-tomcat9-mariadb (change xwiki-tomcat9-mariadb for the top level package you installed if you installed something else).

Warning

Sometimes (especially in case of new cycle), apt upgrade might report that it refuse to upgrade some xwiki packages.

This is generally the sign that either:

  • A new dependency cannot be found: it generally means that XWiki starts requiring a more recent version of Java and the Debian repository you have don't have any implementation of this Java versions. See No package can be found for Java for more details on how to resolve this situation.
  • Some xwiki package name changed: this generally happen when XWiki stops supporting some version of Tomcat and you need to install a different xwiki-tomcat* package (for example XWiki 17 does not support tomcat9 anymore and requires the tomcat10 package so xwiki packages for this version have been renamed to xwiki-tomcat10-mariadb for example, if you used mariadb).

Upgrade the pages

Like in the case of the install, you still have to go through the Distribution Wizard. See more details on Upgrading the flavor.

Uninstallation

If you want to remove XWiki from your system, you only have to uninstall the packages you've installed at the beginning of this documentation. For example:

sudo apt-get --purge remove xwiki-common

Attention, these commands do not remove MySQL/PostgreSQL nor Tomcat from your system. To do so, if you don't use these applications for another purpose, you can make some cleaning with

sudo apt-get --purge autoremove

Troubleshooting

Log file location

This installation manual should guide you all the way to a fresh and clean XWiki platform. If on the other hand issues may arise, it is important to inspect the XWiki log file for any WARNING messages that may have been brought up. Below you can find the location of this log file for the respective application servers.

XJetty

/var/log/xwiki/[date].jetty.log

Tomcat

There are several possibilities depending on the distribution and Tomcat version:

/var/log/tomcat10/catalina.out
/var/log/tomcat10/catalina.[date].log
/var/log/tomcat9/catalina.out
/var/log/tomcat9/Catalina.[date].log

You can find a generic Troubleshooting section on https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Installation/#HTroubleshooting.

No package can be found for Java

XWiki require at least Java 17 since XWiki 16.0.

If your Debian based distribution does not provide any package for the Java version you need you can try with:

Tomcat

See Tomcat Installation for generic Tomcat related issues.

MySQL

See MySQL Installation for generic MySQL related issues.

PostgreSQL

See PostgreSQL Installation for generic PostgreSQL related issues.

Other useful info

XWiki as root webapp (short URLs)

Note that this section is only the part of Short URL specific to the Debian setup. To fully configure the URL to your liking, see full documentation on short URLs.

For Tomcat 9

Warning

When doing it make sure to check after upgrade if all is OK in /etc/tomcat9/Catalina/localhost folder (xwiki.xml might be restored).

  • Rename file /etc/tomcat9/Catalina/localhost/xwiki.xml into /etc/tomcat9/Catalina/localhost/ROOT.xml
  • Edit file /etc/xwiki/xwiki-tomcat9.xml and modify Context XML element path from /xwiki to / as in moving from
    <Context path="/xwiki" docBase="/usr/lib/xwiki"
            containerSciFilter="org.apache.tomcat.websocket.server.WsSci|org.apache.jasper.servlet.JasperInitializer">

    to

    <Context path="" docBase="/usr/lib/xwiki"
            containerSciFilter="org.apache.tomcat.websocket.server.WsSci|org.apache.jasper.servlet.JasperInitializer">
  • Edit file /etc/xwiki/xwiki.cfg and uncomment xwiki.webapppath=
  • Restart Tomcat 9.

For Jetty

XWiki 16.7.0+

You have to modify the xjetty-web.xml file

The WebAppContext from the xwiki-jetty configuration has to be modified so that Jetty actually serves the XWiki application from the root-path. For this you have to modify the /etc/xwiki/xjetty-web.xml and add the following directive.

<Set name="contextPath">/</Set>

Integrate with LibreOffice

Install libreoffice with sudo apt-get install libreoffice.

And setup XWiki to automatically start and access libreoffice in /etc/xwiki/xwiki.properties:

openoffice.autoStart=true
openoffice.homePath=/usr/lib/libreoffice/

See Office Importer Application for more details.

Standalone Solr setup

Take a look at Solr documentation to install Solr itself.

Then you will need to add the XWiki schema configuration: you should install the package xwiki-solr-all for Solr 8 or XWiki XWiki 16.2.0+ xwiki-solr9-all for Solr 9 to automatically register the Solr cores needed by XWiki Standard in the Solr server (provided the standard Solr setup was used).

Access a file from XWiki

SystemD is configured to prevent XWiki from accessing an arbitrary file on the file system, even if the system user which runs XWiki would normally be allowed to access it. You can control this in the file /etc/systemd/system/tomcat9.service.d/xwiki-tomcat9-systemd.conf when using xwiki-tomcat9-common and /lib/systemd/system/xwiki.service when using xwiki-xjetty-common and by the default XWiki is allowed and write /var/lib/xwiki/data. Note that once you modified one of those files, you will need to execute sudo systemctl daemon-reload and restart the service.

Overview of the important files

Here is a list of a different tree. The point is to help you find useful files easily. This list is showing a few files and directories, to keep it simple and clear. The '->' is used to show a link to another file/directory.

XWiki

The configuration: /etc/xwiki/

  • hibernate.cfg.xml               Hibernate configuration, helping to configure the database resources
  • xwiki.cfg
  • xwiki.properties
  • xwiki-tomcat9-systemd.conf       Injected trough /etc/systemd/system/tomcat9.service.d/xwiki-tomcat-systemd.conf in the tomcat9 service configuration
  • xwiki-tomcat<version>            The Tomcat integration linked from /etc/tomcat<version>/Catalina/localhost

The permanent directory: /var/lib/xwiki/data

The home directory: /usr/lib/xwiki/

  • META-INF
  • resources
  • skins
  • templates
  • WEB-INF
    • hibernate.cfg.xml -> /etc/xwiki/hibernate.cfg.xml
    • xwiki.cfg -> /etc/xwiki/xwiki.cfg
    • xwiki.properties -> /etc/xwiki/xwiki.properties

XJetty

/lib/systemd/system/xwiki.service is the configuration in charge of controlling the xwiki service, it's also where you can customize its java startup configuration

Tomcat

/etc/tomcat<version>/

  • context.xml
  • logging.properties
  • server.xml
  • tomcat-users.xml
  • web.xml

/etc/default/

  • tomcat<version>                 This file helps configuring the Tomcat daemon. Every change needs a restart to be effective

/var/lib/tomcat<version>/

  • common
  • conf -> /etc/tomcat<version>
  • logs -> ../../log/tomcat<version>     Note that starting Debian 10 and Ubuntu 18.04 systemd service log is used
  • server
  • shared
  • webapps

/var/log/tomcat<version>/

  • catalina.out            First logging file. Check this one if you're experiencing troubles with Tomcat/XWiki.
  • localhost.<date>.log     "Container Log file": Start of each filter and failures thereof are listed.

MariaDB/MySQL

/etc/mysql/

  • debian.cnf
  • my.cnf                  Database configuration. Max_allowed_packet is the parameter you  need to change to improve upload data size. permitted.

/var/lib/mysql/

  • mysql
  • xwiki                   This is the xwiki database. You may want to backup this directory from time to time.

/var/log/

  • syslog
  • mysql
    • error.log

PostgreSQL

/etc/postgresql/

  • <version>
    • main
      • postgresql.conf
      • pg_hba.conf

/var/lib/postgresql/<version>/main/

  • base

Get Connected