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