Skip to Content

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