Installation using Debian (.DEB) packages

Version 196.4 by Thomas Mortagne on 2021/01/13

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.

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:

wget -q "https://maven.xwiki.org/public.gpg" -O- | sudo apt-key add -
sudo wget "https://maven.xwiki.org/stable/xwiki-stable.list" -P /etc/apt/sources.list.d/

Note that there is 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

It shows the following packages (the exact list depends on the version the repository contains):

  • 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
  • xwiki-tomcat8-common - XWiki Tomcat 8 common package, you can install this if you want to take care yourself of the database link
  • xwiki-tomcat9-common - XWiki Tomcat 9 common package, you can install this if you want to take care yourself of the database link
  • xwiki-tomcat8-mariadb - XWiki Tomcat 8/MariaDB based package
  • xwiki-tomcat9-mariadb - XWiki Tomcat 9/MariaDB based package
  • xwiki-tomcat8-mysql - XWiki Tomcat 8/MySQL based package
  • xwiki-tomcat9-mysql - XWiki Tomcat 9/MySQL based package
  • xwiki-tomcat8-pgsql - XWiki Tomcat 8/PostgreSQL
  • xwiki-tomcat9-pgsql - XWiki Tomcat 9/PostgreSQL
  • xwiki-solr-all - An entry point package which a dependency on all the solr core required to setup a standalone version compatible with XWiki Standard
  • xwiki-solr-core - A pre configured Solr core for the XWiki search feature
  • xwiki-solr-events - A pre configured Solr core for the XWiki events/notifications storage
  • xwiki-solr-ratings - A pre configured Solr core for the XWiki rating storage

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

xwiki-enterprise-* packages were deprecated as of 9.4. Installations requiring those packages will appear to have stopped updating at version 9.4. Install the corresponding xwiki-* package to update to the latest version. (For example, if you were relying on the xwiki-enterprise-tomcat8-mysql package, you will now need to install the xwiki-tomcat8-mysql package.)

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.

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

Complete Installation

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 Usability section for more details.

Using MariaDB

Note that XWiki require at least MariaDB 5.10. If your Debian distribution provide an older version (like Debian Stretch/9) you can use the one from the repositories provided by the MariaDB project to get a more recent version on https://downloads.mariadb.org/mariadb/repositories/.

The following will install everything you need to run XWiki with MariaDB and Tomcat 9:

sudo apt-get install xwiki-tomcat9-mariadb

This package depends on xwiki-common, xwiki-tomcat9-common, xwiki-mariadb-common, mariadb-server and tomcat9. You might have to select a different version of Tomcat depending on what's available in your system repository.

During the installation, you may have some questions from dbconfig, in charge of the configuration of the database. Don't confuse it with the MariaDB root password prompt, which beg you to put a password for the superuser.
DBconfig prompt is about the configuration of xwiki and mariadb. If you haven't any mariadb already installed and you aren't familiar with it, you should let dbconfig handle this.

DBconfig is then asking you for the mariadb root password (you may have entered before). Then, you can choose the password for the "xwiki" mariadb user. This user will be used to connect from XWiki application. Choose it wisely, but you don't have to pay a lot of attention to it, because after that, dbconfig is configuring XWiki automatically with these credentials.

The installation now ends, with the automatic start of tomcat daemon ("Starting Tomcat servlet engine tomcat9      [OK]").

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

Using MySQL

Note that XWiki require at least MySQL 5.7. This package also works with MariaDB (in which case you need at least MariaDB 10.2).

The following will install everything you need to run XWiki with MySQL and Tomcat 9:

sudo apt-get install xwiki-tomcat9-mysql

This package depends on xwiki-common, xwiki-tomcat9-common, xwiki-mysql-common, mysql-server and tomcat9. You might have to select a different version of Tomcat depending on what's available in your system repository.

During the installation, you may have some questions from dbconfig, in charge of the configuration of the database. Don't confuse it with the MySQL root password prompt, which beg you to put a password for the superuser.
DBconfig prompt is about the configuration of xwiki and mysql. If you haven't any mysql already installed and you aren't familiar with it, you should let dbconfig handle this.

DBconfig is then asking you for the mysql root password (you may have entered before). Then, you can choose the password for the "xwiki" mysql user. This user will be used to connect from XWiki application. Choose it wisely, but you don't have to pay a lot of attention to it, because after that, dbconfig is configuring XWiki automatically with these credentials.

The installation now ends, with the automatic start of tomcat daemon ("Starting Tomcat servlet engine tomcat9      [OK]").

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

Using PostgreSQL

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

sudo apt-get install xwiki-tomcat9-pgsql

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

PostgreSQL is slightly different than MySQL in the handling of databases and in the manual configuration, but everything should work on the first try.

Security settings

  1. Open /etc/xwiki/xwiki.cfg file and change lines:

    ...
    #-# Cookie encryption keys. You SHOULD replace these values with any random string,
    #-# as long as the length is the same.
    xwiki.authentication.validationKey=your1stkeyhere
    xwiki.authentication.encryptionKey=your2ndkeyhere
    ...
  2. If you need, add password to the built-in superadmin account, by changing line:

    ...
    #-# Enable to allow superadmin. It is disabled by default as this could be a
    #-# security breach if it were set and you forgot about it. Should only be enabled
    #-# for recovering the Wiki when the rights are completely messed.
    xwiki.superadminpassword=yourpassword
    ...

Tomcat Usability

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/tomcat9 (or /etc/default/tomcat8 for Tomcat 8, etc).

Memory

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

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

Modify the property JAVA_OPTS. For example:

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

You should check the Memory settings we recommend.

/dev/urandom

In most Debian-based systems the default random implementation is /dev/random which can be very slow. /dev/urandom is much faster and it's fine for XWiki's needs so you should use it when possible:

  • edit /etc/default/tomcat9 file and add
JAVA_OPTS="${JAVA_OPTS} -Djava.security.egd=file:/dev/./urandom"

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

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=

Uninstallation

If you want to remove XWiki from your system, you only have to uninstall the package 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

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

Getting "The repository 'http://maven.xwiki.org stable/ Release' is no longer signed."

The repository is signed but the key changed on November 4th 2020 so if you registered it before that you will need to register the new one:

wget -q "https://maven.xwiki.org/public.gpg" -O- | sudo apt-key add -

No package can be found for Java

XWiki require at least Java 8 since XWiki 8.1, OpenJDK 11 (the recommended version) will be automatically installed as dependency on recent distributions.

For some older distributions the problem is that Ubuntu and Debian did not bothered put OpenJDK 8 on older but still supported distributions default repositories (for example Ubuntu 14.04 or Debian Wheezy/Jessie). For those you will have to make sure there is some repository with it so that Java 8+ is installed as a package so that XWiki find it as dependency.

Here is a few helpers for specific distributions:

Ubuntu 14.04 (Trusty Tahr), Debian < 9

My wiki is empty after upgrading a Tomcat9 based package

Upgrading from another Tomcat 9 based package

This generally means that you installed a Tomcat 9 based package before one of 10.11.11, 11.3.7, 12.0-rc-1 or 11.10.3 and the data were stored in a temporary location (generally /var/cache/tomcat9/Catalina/localhost/xwiki).

You will need to find where was the data stored and move it to /var/lib/xwiki/data.

If you don't find the previous data take a look at a previous logs (in /var/log/tomcat9/) and search for "Falling back on".

Previous from a package based on a version of Tomcat lower than 9

This is caused by the bug https://jira.xwiki.org/browse/XWIKI-16943 which is fixed in 10.11.11, 11.3.7, 12.0-rc-1 an 11.10.3.

The workaround is to execute the following commands:

  • mkdir /etc/systemd/system/tomcat9.service.d/
  • echo -e "[Service]\nReadWritePaths=/var/lib/xwiki/data" > /etc/systemd/system/tomcat9.service.d/override.conf
  • systemctl daemon-reload
  • systemctl restart tomcat9.service

I get an error when using the chart macro

The chart macro doesn't appear to be working with a clean install with the openjdk 8 Debian package (openjdk 11, which is the recommended version, does not seems to be affected). It gives an error:

 Failed to execute the [chart] macro. Cause: [Could not initialize class org.jfree.chart.JFreeChart].

In some Debian/Ubuntu version a broken accessibility option is enabled by default on Java 8 and it's what is causing this error. See https://jira.xwiki.org/browse/XWIKI-16993 and https://bugs.launchpad.net/ubuntu/+source/openjdk-6/+bug/935296 for more details.

To disable it go to /etc/java-8-openjdk/accessibility.properties (or another path depending on your version of Java) and comment the line:

# assistive_technologies=org.GNOME.Accessibility.AtkWrapper

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)

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=

Note that this is only the part of Short URL which is specific to the Debian setup, for the rest you will have to look at the generic documentation.

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 it.

Then you will need to add the XWiki schema configuration:

  • since 12.6 you should install the package xwiki-solr-all to automatically register the Solr cores needed by XWiki Standard in the Solr server (provided the standard setup was used)
  • between 12.0 and 12.5 the package xwiki-solr-core will automatically register the XWiki search core in the Solr server (provided the standard setup was used)
  • before 12.0 you can use the xwiki-solr-data Debian package and add some links to register it in your Solr server

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

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

/etc/init.d/

  • tomcat<version>                 Daemon start/stop script

/var/lib/tomcat<version>/

  • common
  • conf -> /etc/tomcat<version>
  • logs -> ../../log/tomcat<version>
  • 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.

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

Get Connected