Last modified by Jan-Paul Kleijn on 2023/01/07
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 is 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 (beta)
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]]: the current "long term support" branch versions as defined in [[Support page>>xwiki:Main.Support]]
24 {{/info}}
25
26 Now you can update the packages database to read the data from this repository.
27
28 {{code language="bash"}}
29 sudo apt-get update
30 {{/code}}
31
32 Now you can make a little search to see what this repo offers.
33
34 {{code language="bash"}}
35 apt-cache search xwiki
36 {{/code}}
37
38 It shows the following packages (the exact list depends on the version the repository contains):
39
40 * xwiki-common - XWiki, you can install this if you want to take care yourself of the database and application server
41 * xwiki-mariadb-common - XWiki MariaDB common package, you can install this if you want to take care yourself of the application server
42 * xwiki-mysql-common - XWiki MySQL common package, you can install this if you want to take care yourself of the application server
43 * xwiki-pgsql-common - XWiki PostgreSQL common package, you can install this if you want to take care yourself of the application server
44 * xwiki-tomcat8-common - XWiki Tomcat 8 common package, you can install this if you want to take care yourself of the database link
45 * xwiki-tomcat9-common - XWiki Tomcat 9 common package, you can install this if you want to take care yourself of the database link
46 * xwiki-tomcat8-mariadb - XWiki Tomcat 8/MariaDB based package
47 * xwiki-tomcat9-mariadb - XWiki Tomcat 9/MariaDB based package
48 * xwiki-tomcat8-mysql - XWiki Tomcat 8/MySQL based package
49 * xwiki-tomcat9-mysql - XWiki Tomcat 9/MySQL based package
50 * xwiki-tomcat8-pgsql - XWiki Tomcat 8/PostgreSQL
51 * xwiki-tomcat9-pgsql - XWiki Tomcat 9/PostgreSQL
52 * 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
53 * xwiki-solr-core - A pre configured Solr core for the XWiki search feature
54 * xwiki-solr-events - A pre configured Solr core for the XWiki events/notifications storage
55 * xwiki-solr-ratings - A pre configured Solr core for the XWiki rating storage
56
57 Plus legacy packages from older versions of XWiki like xwiki-enterprise-* packages or for unsupported versions of Tomcat.
58
59 {{error}}
60 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.)
61 {{/error}}
62
63 {{info}}
64 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.
65 {{/info}}
66
67 {{warning}}
68 On Ubuntu you will need [[##universe## repository>>https://help.ubuntu.com/community/Repositories/CommandLine]] to install Tomcat packages. It's generally enabled by default.
69 {{/warning}}
70
71 == Complete Installation ==
72
73 {{warning}}
74 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.
75 {{/warning}}
76
77 === Using MariaDB ===
78
79 {{warning}}
80 Note that XWiki require at least MariaDB 10.2. 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/.
81 {{/warning}}
82
83 The following will install everything you need to run XWiki with MariaDB and Tomcat 9:
84
85 {{code language="bash"}}
86 sudo apt-get install xwiki-tomcat9-mariadb
87 {{/code}}
88
89 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.
90
91 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.
92
93 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.
94
95 {{warning}}
96 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]]
97 {{/warning}}
98
99 The installation ends with the start of the Tomcat daemon ("Starting Tomcat servlet engine tomcat9 [OK]") which is also setup to start automatically from boot.
100
101 === Using MySQL ===
102
103 {{warning}}
104 Note that XWiki requires at least MySQL 5.7. This package also works with MariaDB (in which case you need at least MariaDB 10.2).
105 {{/warning}}
106
107 The following will install everything you need to run XWiki with MySQL and Tomcat 9:
108
109 {{code language="bash"}}
110 sudo apt-get install xwiki-tomcat9-mysql
111 {{/code}}
112
113 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.
114
115 During the installation you may get some questions from DBconfig, which is in charge of the configuration of XWiki with the MySQL database. Don't confuse it with the MySQL root password prompt that asks you for a root password (which is intented for the superuser). If you haven't already installed any MySQL databases and you are not familiar with it you should let DBconfig handle this.
116
117 Afterwards DBconfig asks you for the MySQL root password for the "xwiki" MySQL user. This user will be used to connect to MySQL 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 Tomcat daemon ("Starting Tomcat servlet engine tomcat9 [OK]") which is also setup to start automatically from boot.
124
125 === Using PostgreSQL ===
126
127 It's as simple as the MySQL installation, you only need to choose the right virtual package.
128
129 {{code language="bash"}}
130 sudo apt-get install xwiki-tomcat9-pgsql
131 {{/code}}
132
133 PostgreSQL is slightly different than MySQL in the handling of databases and in the manual configuration, but everything should work on the first try.
134
135 === Starting up XWiki for the first time... ===
136
137 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]]##
138
139 {{warning}}
140 Note that your wiki is absolutely empty, like a WAR installation. Distribution Wizard will take care of the rest.
141 {{/warning}}
142
143 == Security ==
144
145 === Security settings of XWiki ===
146
147 1. (((
148 Open ##/etc/xwiki/xwiki.cfg## file and change lines:
149
150 {{code language="none"}}
151 ...
152 #-# Cookie encryption keys. You SHOULD replace these values with any random string,
153 #-# as long as the length is the same.
154 xwiki.authentication.validationKey=your1stkeyhere
155 xwiki.authentication.encryptionKey=your2ndkeyhere
156 ...
157 {{/code}}
158 )))
159 1. (((
160 If you need, add password to the built-in superadmin account, by changing line:
161
162 {{code language="none"}}
163 ...
164 #-# Enable to allow superadmin. It is disabled by default as this could be a
165 #-# security breach if it were set and you forgot about it. Should only be enabled
166 #-# for recovering of XWiki when the rights are completely messed.
167 xwiki.superadminpassword=yourpassword
168 ...
169 {{/code}}
170 )))
171
172 == Performance ==
173
174 === Tomcat ===
175
176 You can find [[various generic advices and troubleshooting related to Tomcat>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationTomcat.WebHome]].
177
178 === Java Version ===
179
180 Make sure Tomcat is executed with the right [[Java version>>platform:AdminGuide.Installation||anchor="HHardwareandSoftwarerequirements"]].
181
182 This is usually indicated in the file ##/etc/default/tomcat9## (or ##/etc/default/tomcat8## for Tomcat 8, etc).
183
184 === Memory ===
185
186 The default Tomcat memory setup is too low for XWiki's needs.
187
188 You can change it in the file ##/etc/default/tomcat9## (or ##/etc/default/tomcat8## for Tomcat 8, etc).
189
190 Modify the property ##JAVA_OPTS##. For example:
191
192 {{code language="none"}}
193 JAVA_OPTS="-Djava.awt.headless=true -Xmx1024m"
194 {{/code}}
195
196 You should [[check the Memory settings we recommend>>Documentation.AdminGuide.Performances||anchor="HMemory"]].
197
198 === /dev/urandom ===
199
200 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:
201
202 * edit ##/etc/default/tomcat9## file and add
203
204 {{code language="bash"}}
205 JAVA_OPTS="${JAVA_OPTS} -Djava.security.egd=file:/dev/./urandom"
206 {{/code}}
207
208 == Concluding Step ==
209
210 {{include reference="Documentation.AdminGuide.Installation.InstallationConcludingSteps.WebHome"/}}
211
212 == Uninstallation ==
213
214 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:
215
216 {{code language="bash"}}
217 sudo apt-get --purge remove xwiki-common
218 {{/code}}
219
220 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
221
222 {{code language="bash"}}
223 sudo apt-get --purge autoremove
224 {{/code}}
225
226 == Troubleshooting ==
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 Tomcat 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 Tomcat versions.
231
232 **Tomcat8**
233
234 {{code language="none"}}
235 /var/log/tomcat8/Catalina.[date].log
236 {{/code}}
237
238 **Tomcat9**
239
240 {{code language="none"}}
241 /var/log/tomcat9/Catalina.[date].log
242 {{/code}}
243
244 You can find a generic Troubleshooting section on [[https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Installation/#HTroubleshooting]].
245
246 === No package can be found for Java ===
247
248 XWiki require at least Java 8 since XWiki 8.1 and Java 11 since XWiki 14.0, **OpenJDK 11** (the recommended version) will be automatically installed as dependency on recent distributions.
249
250 If your Debian based distribution does not provide any package for the Java version you need you can try with:
251
252 * Adoptium provides a Debian repository to install Temurin (OpenJDK), see https://adoptium.net/installation/linux/#_eclipse_temurin_package_names
253
254 === I get an error when using the chart macro ===
255
256 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:
257
258 > Failed to execute the [chart] macro. Cause: [Could not initialize class org.jfree.chart.JFreeChart].
259
260 In some Debian/Ubuntu versions 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.
261
262 To disable it go to ##/etc/java-8-openjdk/accessibility.properties## (or another path depending on your version of Java) and comment the line:
263
264 {{code language="properties"}}
265 # assistive_technologies=org.GNOME.Accessibility.AtkWrapper
266 {{/code}}
267
268 === Tomcat ===
269
270 See [[Tomcat Installation>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationTomcat||anchor="HTroubleshooting"]] for generic Tomcat related issues.
271
272 === MySQL ===
273
274 See [[MySQL Installation>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationMySQL||anchor="HTroubleshooting"]] for generic MySQL related issues.
275
276 === PostgreSQL ===
277
278 See [[PostgreSQL Installation>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationPostgreSQL||anchor="HTroubleshooting"]] for generic PostgreSQL related issues.
279
280 == Other useful info ==
281
282 === XWiki as root webapp (short URLs) ===
283
284 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]].
285
286 ==== For Tomcat 9 ====
287
288 {{warning}}
289 When doing it make sure to check after upgrade if all is OK in /etc/tomcat9/Catalina/localhost folder (xwiki.xml might be restored).
290 {{/warning}}
291
292 * Rename file ##/etc/tomcat9/Catalina/localhost/xwiki.xml## into ##/etc/tomcat9/Catalina/localhost/ROOT.xml##
293 * Edit file ##/etc/xwiki/xwiki-tomcat9.xml## and modify ##Context## XML element path from ##/xwiki## to ##/## as in moving from(((
294 {{code language="xml"}}
295 <Context path="/xwiki" docBase="/usr/lib/xwiki"
296 containerSciFilter="org.apache.tomcat.websocket.server.WsSci|org.apache.jasper.servlet.JasperInitializer">
297 {{/code}}
298
299 to
300
301 {{code language="xml"}}
302 <Context path="" docBase="/usr/lib/xwiki"
303 containerSciFilter="org.apache.tomcat.websocket.server.WsSci|org.apache.jasper.servlet.JasperInitializer">
304 {{/code}}
305 )))
306 * Edit file ##/etc/xwiki/xwiki.cfg## and uncomment {{code language="properties"}}xwiki.webapppath={{/code}}
307 * Restart Tomcat 9.
308
309 === Integrate with LibreOffice ===
310
311 Install libreoffice with {{code language="none"}}sudo apt-get install libreoffice{{/code}}.
312
313 And setup XWiki to automatically start and access libreoffice in ##/etc/xwiki/xwiki.properties##:
314
315 {{code language="properties"}}
316 openoffice.autoStart=true
317 openoffice.homePath=/usr/lib/libreoffice/
318 {{/code}}
319
320 See [[Office Importer Application>>extensions:Extension.Office Importer Application]] for more details.
321
322 === Standalone Solr setup ===
323
324 Take a look at [[Solr documentation>>https://solr.apache.org/guide/8_8/taking-solr-to-production.html]] to install it.
325
326 Then you will need to add the XWiki schema configuration: 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).
327
328 == Overview of the important files ==
329
330 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.
331
332 === XWiki ===
333
334 The configuration: **/etc/xwiki/**
335
336 * hibernate.cfg.xml //Hibernate configuration, helping to configure the database resources//
337 * xwiki.cfg
338 * xwiki.properties
339 * xwiki-tomcat9-systemd.conf // Injected trough ##/etc/systemd/system/tomcat9.service.d/xwiki-tomcat-systemd.conf##// in the tomcat9 service configuration
340 * xwiki-tomcat<version> // The Tomcat integration linked from ##/etc/tomcat<version>/Catalina/localhost##//
341
342 The permanent directory: **/var/lib/xwiki/data**
343
344 The home directory: **/usr/lib/xwiki/**
345
346 * META-INF
347 * resources
348 * skins
349 * templates
350 * WEB-INF
351 ** hibernate.cfg.xml -> /etc/xwiki/hibernate.cfg.xml
352 ** xwiki.cfg -> /etc/xwiki/xwiki.cfg
353 ** xwiki.properties -> /etc/xwiki/xwiki.properties
354
355 === Tomcat ===
356
357 **/etc/tomcat##<version>##/**
358
359 * context.xml
360 * logging.properties
361 * server.xml
362 * tomcat-users.xml
363 * web.xml
364
365 **/etc/default/**
366
367 * tomcat##<version>## //This file helps configuring the Tomcat daemon. Every change needs a restart to be effective//
368
369 **/var/lib/tomcat##<version>##/**
370
371 * common
372 * conf -> /etc/tomcat##<version>##
373 * logs -> ../../log/tomcat##<version>     //Note that starting Debian 10 and Ubuntu 18.04 systemd service log is used//##
374 * server
375 * shared
376 * webapps
377
378 **/var/log/tomcat##<version>##/**
379
380 * catalina.out //First logging file. Check this one if you're experiencing troubles with Tomcat/XWiki.//
381 * localhost.<date>.log // "Container Log file": Start of each filter and failures thereof are listed.//
382
383 === MySQL ===
384
385 **/etc/mysql/**
386
387 * debian.cnf
388 * my.cnf //Database configuration. Max_allowed_packet is the parameter you need to change to improve upload data size.// permitted.
389
390 **/var/lib/mysql/**
391
392 * mysql
393 * xwiki //This is the xwiki database. You may want to backup this directory from time to time.//
394
395 **/var/log/**
396
397 * syslog
398 * mysql
399 ** error.log
400
401 === PostgreSQL ===
402
403 **/etc/postgresql/**
404
405 * ##<version>##
406 ** main
407 *** postgresql.conf
408 *** pg_hba.conf
409
410 **/var/lib/postgresql/##<version>##/main/**
411
412 * 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