Skip to Content

Version 251.1 by Thomas Mortagne on 2025/02/14
Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc start="2"/}}
3 {{/box}}
4
5 This distribution allows installing XWiki and every component needed for a production instance automatically.
6
7 This method works for all Debian-based linux distribution. Feel free to use [[the User Forum>>dev:Community.Discuss]] to report issues, or discuss about it.
8
9 {{warning}}
10 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:
11
12 * use the xjetty based packages instead
13 * upgrade to XWiki 17+
14 * use an [[alternative non Debian specific install method>>xwiki:Documentation.AdminGuide.Installation||anchor="HInstallationMethods"]].
15 {{/warning}}
16
17 == APT Configuration ==
18
19 First, you have to configure your package manager in order to use XWiki's repository. This can be done simply, using this command:
20
21 {{code language="bash"}}
22 sudo wget https://maven.xwiki.org/xwiki-keyring.gpg -O /usr/share/keyrings/xwiki-keyring.gpg
23 sudo wget "https://maven.xwiki.org/stable/xwiki-stable.list" -O /etc/apt/sources.list.d/xwiki-stable.list
24 {{/code}}
25
26 {{info}}
27 Note that there are several repositories you can choose (as alternatives to the stable one you have in the previous example):
28
29 * [[https:~~/~~/maven.xwiki.org/releases/xwiki-releases.list>>https://maven.xwiki.org/releases/xwiki-releases.list]]: all released versions including milestones and release candidates (beta)
30 * [[https:~~/~~/maven.xwiki.org/stable/xwiki-stable.list>>https://maven.xwiki.org/stable/xwiki-stable.list]]: all released versions excluding milestones and release candidates (stable)
31 * [[https:~~/~~/maven.xwiki.org/lts/xwiki-lts.list>>https://maven.xwiki.org/lts/xwiki-lts.list]]: the current "long term support" branch versions as defined in [[Support page>>xwiki:Main.Support]]
32 {{/info}}
33
34 Now you can update the packages database to read the data from this repository.
35
36 {{code language="bash"}}
37 sudo apt-get update
38 {{/code}}
39
40 Now you can make a little search to see what this repo offers.
41
42 {{code language="bash"}}
43 apt-cache search xwiki
44 {{/code}}
45
46 * Common packages not tied to any application server or database
47 ** ##xwiki-common## - XWiki, you can install this if you want to take care yourself of the database and application server
48 ** ##xwiki-mariadb-common## - XWiki MariaDB common package, you can install this if you want to take care yourself of the application server
49 ** ##xwiki-mysql-common## - XWiki MySQL common package, you can install this if you want to take care yourself of the application server
50 ** ##xwiki-pgsql-common## - XWiki PostgreSQL common package, you can install this if you want to take care yourself of the application server
51
52 * Packages based on a customized Jetty packaged for XWiki
53 ** ##xwiki-xjetty-common## - XWiki Jetty common package, you can install this if you want to take care yourself of the database link
54 ** ##xwiki-xjetty-mariadb## - XWiki Jetty/MariaDB based package
55 ** ##xwiki-xjetty-mysql## - XWiki Jetty/MySQL based package
56 ** ##xwiki-xjetty-pgsql## - XWiki Jetty/PostgreSQL
57
58 * Packages based on the standard Tomcat package
59 ** ##xwiki-tomcat9-common## - XWiki Tomcat 9 common package, you can install this if you want to take care yourself of the database link
60 ** ##xwiki-tomcat10-common## - XWiki Tomcat 10 common package, you can install this if you want to take care yourself of the database link
61 ** ##xwiki-tomcat9-mariadb## - XWiki Tomcat 9/MariaDB based package
62 ** ##xwiki-tomcat10-mariadb## - XWiki Tomcat 10/MariaDB based package
63 ** ##xwiki-tomcat9-mysql## - XWiki Tomcat 9/MySQL based package
64 ** ##xwiki-tomcat10-mysql## - XWiki Tomcat 10/MySQL based package
65 ** ##xwiki-tomcat9-pgsql## - XWiki Tomcat 9/PostgreSQL
66 ** ##xwiki-tomcat10-pgsql## - XWiki Tomcat 10/PostgreSQL
67
68 * Not really XWiki itself but Solr cores needed when you want to use a standalone Solr instance with XWiki
69 ** ##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
70 ** ##xwiki-solr9-search## - A pre configured Solr 9 core for the XWiki search feature
71 ** ##xwiki-solr9-events## - A pre configured Solr 9 core for the XWiki events/notifications storage
72 ** ##xwiki-solr9-ratings## - A pre configured Solr 9 core for the XWiki rating storage
73 ** ##xwiki-solr9-extension_index## - A pre configured Solr 9 core for the XWiki extensions index
74
75 Plus legacy packages from older versions of XWiki like ##xwiki-enterprise-*## packages or for unsupported versions of Tomcat.
76
77 {{info}}
78 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.
79 {{/info}}
80
81 {{warning}}
82 On Ubuntu you will need [[##universe## repository>>https://help.ubuntu.com/community/Repositories/CommandLine]] to install Tomcat packages. It's generally enabled by default.
83 {{/warning}}
84
85 == Complete Installation ==
86
87 {{warning}}
88 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>>||anchor="HTomcatUsability"]] for more details.
89 {{/warning}}
90
91 === Using MariaDB ===
92
93 {{warning}}
94 Note that XWiki requires at least MariaDB 10.2.
95 {{/warning}}
96
97 Xjetty:
98
99 {{code language="bash"}}
100 sudo apt install xwiki-xjetty-mariadb
101 {{/code}}
102
103 Tomcat 10:
104
105 {{code language="bash"}}
106 sudo apt install xwiki-tomcat10-mariadb
107 {{/code}}
108
109 Tomcat 9:
110
111 {{code language="bash"}}
112 sudo apt install xwiki-tomcat9-mariadb
113 {{/code}}
114
115 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.
116
117 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.
118
119 {{warning}}
120 The password should not contain any special characters, otherwise XWiki will fail to start. See [[https:~~/~~/jira.xwiki.org/browse/XWIKI-14406>>https://jira.xwiki.org/browse/XWIKI-14406]]
121 {{/warning}}
122
123 The installation ends with the start of the XWiki or Tomcat daemon which is also setup to start automatically from boot.
124
125 === Using MySQL ===
126
127 {{warning}}
128 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>>||anchor="#HUsingMariaDB"]].
129 {{/warning}}
130
131 Xjetty:
132
133 {{code language="bash"}}
134 sudo apt install xwiki-xjetty-mysql
135 {{/code}}
136
137 Tomcat 10:
138
139 {{code language="bash"}}
140 sudo apt install xwiki-tomcat10-mysql
141 {{/code}}
142
143 Tomcat 9:
144
145 {{code language="bash"}}
146 sudo apt install xwiki-tomcat9-mysql
147 {{/code}}
148
149 Everything else is similar to what is described in the [[the MariaDB section>>||anchor="#HUsingMariaDB"]].
150
151 === Using PostgreSQL ===
152
153 It's as simple as the MySQL installation, you only need to choose the right virtual package.
154
155 Xjetty:
156
157 {{code language="bash"}}
158 sudo apt install xwiki-xjetty-pgsql
159 {{/code}}
160
161 Tomcat 10:
162
163 {{code language="bash"}}
164 sudo apt install xwiki-tomcat10-pgsql
165 {{/code}}
166
167 Tomcat 9:
168
169 {{code language="bash"}}
170 sudo apt install xwiki-tomcat9-pgsql
171 {{/code}}
172
173 Everything else is similar to what is described in the [[the MariaDB section>>||anchor="#HUsingMariaDB"]].
174
175 === Starting up XWiki for the first time... ===
176
177 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>>http://localhost:8080/xwiki]]##
178
179 {{warning}}
180 Note that your wiki is absolutely empty, like a WAR installation. Distribution Wizard will take care of the rest.
181 {{/warning}}
182
183 == Performance ==
184
185 === XWiki ===
186
187 You can find various [[various generic advices and troubleshooting related to XWiki>>Documentation.AdminGuide.Performances]].
188
189 === Tomcat ===
190
191 You can find [[various generic advices and troubleshooting related to Tomcat>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationTomcat.WebHome]].
192
193 ==== Java Version ====
194
195 Make sure Tomcat is executed with the right [[Java version>>Documentation.AdminGuide.Installation||anchor="HHardwareandSoftwarerequirements"]].
196
197 This is usually indicated in the file ##/etc/default/tomcat10## (or ##/etc/default/tomcat9## for Tomcat 9, etc).
198
199 ==== Memory ====
200
201 The default Tomcat memory setup is too low for XWiki's needs.
202
203 You can change it in the file ##/etc/default/tomcat10## (or ##/etc/default/tomcat9## for Tomcat 10, etc).
204
205 Modify the property ##JAVA_OPTS##. For example:
206
207 {{code language="none"}}
208 JAVA_OPTS="-Djava.awt.headless=true -Xmx1024m"
209 {{/code}}
210
211 You should [[check the Memory settings we recommend>>Documentation.AdminGuide.Performances||anchor="HMemory"]].
212
213 == Concluding Step ==
214
215 {{include reference="Documentation.AdminGuide.Installation.InstallationConcludingSteps.WebHome"/}}
216
217 == Upgrading ==
218
219 === Update the packages index
220
221 {{code language="bash"}}
222 sudo apt update
223 {{/code}}
224
225 === Upgrade the packages
226
227 {{code language="bash"}}
228 sudo apt upgrade
229 {{/code}}
230
231 This will upgrade all packages, not just XWiki. If you want to avoid all the other packages and only update XWiki, you can use {{code}}sudo apt install xwiki-tomcat9-mariadb{{/code}} (change ##xwiki-tomcat9-mariadb## for the top level package you installed if you installed something else).
232
233 {{warning}}
234 Sometimes (especially in case of new cycle), apt upgrade might report that it refuse to upgrade some xwiki packages.
235
236 This is generally the sign that either:
237 * 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>>Documentation.AdminGuide.Installation.InstallationViaAPT||anchor="HNopackagecanbefoundforJava"]] for more details on how to resolve this situation.
238 * 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##).
239 {{/warning}}
240
241 === Upgrade the pages
242
243 Like in the case of the install, you still have to go through the Distribution Wizard. See more details on [[Upgrading the flavor>>Documentation.AdminGuide.Upgrade||anchor="HPart2Upgradingtheflavor"]].
244
245 == Uninstallation ==
246
247 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:
248
249 {{code language="bash"}}
250 sudo apt-get --purge remove xwiki-common
251 {{/code}}
252
253 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
254
255 {{code language="bash"}}
256 sudo apt-get --purge autoremove
257 {{/code}}
258
259 == Troubleshooting ==
260
261 === Log file location ===
262
263 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.
264
265 ==== XJetty ====
266
267 {{code language="none"}}
268 /var/log/xwiki/[date].jetty.log
269 {{/code}}
270
271 ==== Tomcat9 ====
272
273 There are several possibilities depending on the distribution:
274
275 {{code language="none"}}
276 /var/log/tomcat9/catalina.out
277 /var/log/tomcat9/Catalina.[date].log
278 {{/code}}
279
280 You can find a generic Troubleshooting section on [[https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Installation/#HTroubleshooting]].
281
282 === No package can be found for Java ===
283
284 XWiki require at least Java 8 since XWiki 8.1 and Java 11 since XWiki 14.0, **OpenJDK 17** (the recommended version) will be automatically installed as dependency on recent distributions.
285
286 If your Debian based distribution does not provide any package for the Java version you need you can try with:
287
288 * Adoptium provides a Debian repository to install Temurin (OpenJDK), see https://adoptium.net/installation/linux/#_deb_installation_on_debian_or_ubuntu
289
290 === Tomcat ===
291
292 See [[Tomcat Installation>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationTomcat||anchor="HTroubleshooting"]] for generic Tomcat related issues.
293
294 === MySQL ===
295
296 See [[MySQL Installation>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationMySQL||anchor="HTroubleshooting"]] for generic MySQL related issues.
297
298 === PostgreSQL ===
299
300 See [[PostgreSQL Installation>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationPostgreSQL||anchor="HTroubleshooting"]] for generic PostgreSQL related issues.
301
302 == Other useful info ==
303
304 === XWiki as root webapp (short URLs) ===
305
306 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>>doc:Documentation.AdminGuide.ShortURLs.WebHome]].
307
308 ==== For Tomcat 9 ====
309
310 {{warning}}
311 When doing it make sure to check after upgrade if all is OK in /etc/tomcat9/Catalina/localhost folder (xwiki.xml might be restored).
312 {{/warning}}
313
314 * Rename file ##/etc/tomcat9/Catalina/localhost/xwiki.xml## into ##/etc/tomcat9/Catalina/localhost/ROOT.xml##
315 * Edit file ##/etc/xwiki/xwiki-tomcat9.xml## and modify ##Context## XML element path from ##/xwiki## to ##/## as in moving from(((
316 {{code language="xml"}}
317 <Context path="/xwiki" docBase="/usr/lib/xwiki"
318 containerSciFilter="org.apache.tomcat.websocket.server.WsSci|org.apache.jasper.servlet.JasperInitializer">
319 {{/code}}
320
321 to
322
323 {{code language="xml"}}
324 <Context path="" docBase="/usr/lib/xwiki"
325 containerSciFilter="org.apache.tomcat.websocket.server.WsSci|org.apache.jasper.servlet.JasperInitializer">
326 {{/code}}
327 )))
328 * Edit file ##/etc/xwiki/xwiki.cfg## and uncomment {{code language="properties"}}xwiki.webapppath={{/code}}
329 * Restart Tomcat 9.
330
331 ==== For Jetty ====
332
333 {{version since="16.7.0"}}
334 You have to modify the ##xjetty-web.xml## file
335
336 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.
337
338 {{code language="xml"}}
339 <Set name="contextPath">/</Set>
340 {{/code}}
341 {{/version}}
342
343 === Integrate with LibreOffice ===
344
345 Install libreoffice with {{code language="none"}}sudo apt-get install libreoffice{{/code}}.
346
347 And setup XWiki to automatically start and access libreoffice in ##/etc/xwiki/xwiki.properties##:
348
349 {{code language="properties"}}
350 openoffice.autoStart=true
351 openoffice.homePath=/usr/lib/libreoffice/
352 {{/code}}
353
354 See [[Office Importer Application>>extensions:Extension.Office Importer Application]] for more details.
355
356 === Standalone Solr setup ===
357
358 Take a look at [[Solr documentation>>https://solr.apache.org/guide/solr/latest/deployment-guide/taking-solr-to-production.html]] to install Solr itself.
359
360 Then you will need to add the XWiki schema configuration: you should install the package ##xwiki-solr-all## for Solr 8 or {{version since="XWiki 16.2.0"}}##xwiki-solr9-all## for Solr 9{{/version}} to automatically register the Solr cores needed by XWiki Standard in the Solr server (provided the standard Solr setup was used).
361
362 === Access a file from XWiki ===
363
364 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.
365
366 == Overview of the important files ==
367
368 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.
369
370 === XWiki ===
371
372 The configuration: **/etc/xwiki/**
373
374 * hibernate.cfg.xml //Hibernate configuration, helping to configure the database resources//
375 * xwiki.cfg
376 * xwiki.properties
377 * xwiki-tomcat9-systemd.conf // Injected trough ##/etc/systemd/system/tomcat9.service.d/xwiki-tomcat-systemd.conf##// in the tomcat9 service configuration
378 * xwiki-tomcat<version> // The Tomcat integration linked from ##/etc/tomcat<version>/Catalina/localhost##//
379
380 The permanent directory: **/var/lib/xwiki/data**
381
382 The home directory: **/usr/lib/xwiki/**
383
384 * META-INF
385 * resources
386 * skins
387 * templates
388 * WEB-INF
389 ** hibernate.cfg.xml -> /etc/xwiki/hibernate.cfg.xml
390 ** xwiki.cfg -> /etc/xwiki/xwiki.cfg
391 ** xwiki.properties -> /etc/xwiki/xwiki.properties
392
393 === XJetty ===
394
395 **/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
396
397 === Tomcat ===
398
399 **/etc/tomcat##<version>##/**
400
401 * context.xml
402 * logging.properties
403 * server.xml
404 * tomcat-users.xml
405 * web.xml
406
407 **/etc/default/**
408
409 * tomcat##<version>## //This file helps configuring the Tomcat daemon. Every change needs a restart to be effective//
410
411 **/var/lib/tomcat##<version>##/**
412
413 * common
414 * conf -> /etc/tomcat##<version>##
415 * logs -> ../../log/tomcat##<version>     //Note that starting Debian 10 and Ubuntu 18.04 systemd service log is used//##
416 * server
417 * shared
418 * webapps
419
420 **/var/log/tomcat##<version>##/**
421
422 * catalina.out //First logging file. Check this one if you're experiencing troubles with Tomcat/XWiki.//
423 * localhost.<date>.log // "Container Log file": Start of each filter and failures thereof are listed.//
424
425 === MariaDB/MySQL ===
426
427 **/etc/mysql/**
428
429 * debian.cnf
430 * my.cnf //Database configuration. Max_allowed_packet is the parameter you need to change to improve upload data size.// permitted.
431
432 **/var/lib/mysql/**
433
434 * mysql
435 * xwiki //This is the xwiki database. You may want to backup this directory from time to time.//
436
437 **/var/log/**
438
439 * syslog
440 * mysql
441 ** error.log
442
443 === PostgreSQL ===
444
445 **/etc/postgresql/**
446
447 * ##<version>##
448 ** main
449 *** postgresql.conf
450 *** pg_hba.conf
451
452 **/var/lib/postgresql/##<version>##/main/**
453
454 * base

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected