Version 202.1 by Thomas Mortagne on 2021/08/09
Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
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 wget -q "https://maven.xwiki.org/public.gpg" -O- | sudo apt-key add -
15 sudo wget "https://maven.xwiki.org/stable/xwiki-stable.list" -P /etc/apt/sources.list.d/
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 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.
92 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.
93
94 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.
95
96 The installation now ends, with the automatic start of tomcat daemon ("Starting Tomcat servlet engine tomcat9 [OK]").
97
98 {{warning}}
99 Note that your wiki is absolutely empty, like a WAR installation. Distribution Wizard will take care of the rest.
100 {{/warning}}
101
102 == Using MySQL ==
103
104 {{warning}}
105 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).
106 {{/warning}}
107
108 The following will install everything you need to run XWiki with MySQL and Tomcat 9:
109
110 {{code language="bash"}}
111 sudo apt-get install xwiki-tomcat9-mysql
112 {{/code}}
113
114 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.
115
116 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.
117 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.
118
119 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.
120
121 The installation now ends, with the automatic start of tomcat daemon ("Starting Tomcat servlet engine tomcat9 [OK]").
122
123 {{warning}}
124 Note that your wiki is absolutely empty, like a WAR installation. Distribution Wizard will take care of the rest.
125 {{/warning}}
126
127 == Using PostgreSQL ==
128
129 It's as simple as the MySQL installation, you only need to choose the right virtual package.
130
131 {{code language="bash"}}
132 sudo apt-get install xwiki-tomcat9-pgsql
133 {{/code}}
134
135 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##
136
137 PostgreSQL is slightly different than MySQL in the handling of databases and in the manual configuration, but everything should work on the first try.
138
139 == Security settings ==
140
141 1. (((
142 Open ##/etc/xwiki/xwiki.cfg## file and change lines:
143
144 {{code language="none"}}
145 ...
146 #-# Cookie encryption keys. You SHOULD replace these values with any random string,
147 #-# as long as the length is the same.
148 xwiki.authentication.validationKey=your1stkeyhere
149 xwiki.authentication.encryptionKey=your2ndkeyhere
150 ...
151 {{/code}}
152 )))
153 1. (((
154 If you need, add password to the built-in superadmin account, by changing line:
155
156 {{code language="none"}}
157 ...
158 #-# Enable to allow superadmin. It is disabled by default as this could be a
159 #-# security breach if it were set and you forgot about it. Should only be enabled
160 #-# for recovering the Wiki when the rights are completely messed.
161 xwiki.superadminpassword=yourpassword
162 ...
163 {{/code}}
164 )))
165
166 == Tomcat Usability ==
167
168 You can find [[various generic advices and troubleshooting related to Tomcat>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationTomcat.WebHome]].
169
170 === Java Version ===
171
172 Make sure Tomcat is executed with the right [[Java version>>platform:AdminGuide.Installation||anchor="HHardwareandSoftwarerequirements"]].
173
174 This is usually indicated in the file ##/etc/default/tomcat9## (or ##/etc/default/tomcat8## for Tomcat 8, etc).
175
176 === Memory ===
177
178 The default Tomcat memory setup is too low for XWiki's needs.
179
180 You can change it in the file ##/etc/default/tomcat9## (or ##/etc/default/tomcat8## for Tomcat 8, etc).
181
182 Modify the property ##JAVA_OPTS##. For example:
183
184 {{code language="none"}}
185 JAVA_OPTS="-Djava.awt.headless=true -Xmx1024m"
186 {{/code}}
187
188 You should [[check the Memory settings we recommend>>Documentation.AdminGuide.Performances||anchor="HMemory"]].
189
190 === /dev/urandom ===
191
192 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:
193
194 * edit ##/etc/default/tomcat9## file and add
195
196 {{code language="bash"}}
197 JAVA_OPTS="${JAVA_OPTS} -Djava.security.egd=file:/dev/./urandom"
198 {{/code}}
199
200 = Concluding Step =
201
202 {{include reference="Documentation.AdminGuide.Installation.InstallationConcludingSteps.WebHome"/}}
203
204 = Uninstallation =
205
206 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:
207
208 {{code language="bash"}}
209 sudo apt-get --purge remove xwiki-common
210 {{/code}}
211
212 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
213
214 {{code language="bash"}}
215 sudo apt-get --purge autoremove
216 {{/code}}
217
218 = Troubleshooting =
219
220 You can find a generic Troubleshooting section on [[https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Installation/#HTroubleshooting]].
221
222 == Getting "##The repository 'http:~/~/maven.xwiki.org stable/ Release' is no longer signed.##" ==
223
224 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:
225
226 {{code language="bash"}}
227 wget -q "https://maven.xwiki.org/public.gpg" -O- | sudo apt-key add -
228 {{/code}}
229
230 == No package can be found for Java ==
231
232 XWiki require at least Java 8 since XWiki 8.1, **OpenJDK 11** (the recommended version) will be automatically installed as dependency on recent distributions.
233
234 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.
235
236 Here is a few helpers for specific distributions:
237
238 === Ubuntu 14.04 (Trusty Tahr), Debian < 9 ===
239
240 * AdoptOpenJDK provide a Debian repository to install OpenJDK, see https://adoptopenjdk.net/installation.html#linux-pkg
241
242 == My wiki is empty after upgrading a Tomcat9 based package ==
243
244 === Upgrading from another Tomcat 9 based package ===
245
246 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).
247
248 You will need to find where was the data stored and move it to ##/var/lib/xwiki/data##.
249
250 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".
251
252 === Previous from a package based on a version of Tomcat lower than 9 ===
253
254 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.
255
256 The workaround is to execute the following commands:
257
258 * {{code language="sh"}}mkdir /etc/systemd/system/tomcat9.service.d/{{/code}}
259 * {{code language="sh"}}echo -e "[Service]\nReadWritePaths=/var/lib/xwiki/data" > /etc/systemd/system/tomcat9.service.d/override.conf{{/code}}
260 * {{code language="sh"}}systemctl daemon-reload{{/code}}
261 * {{code language="sh"}}systemctl restart tomcat9.service{{/code}}
262
263 == I get an error when using the chart macro ==
264
265 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:
266
267 > Failed to execute the [chart] macro. Cause: [Could not initialize class org.jfree.chart.JFreeChart].
268
269 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.
270
271 To disable it go to ##/etc/java-8-openjdk/accessibility.properties## (or another path depending on your version of Java) and comment the line:
272
273 {{code language="properties"}}
274 # assistive_technologies=org.GNOME.Accessibility.AtkWrapper
275 {{/code}}
276
277 == Tomcat ==
278
279 See [[Tomcat Installation>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationTomcat||anchor="HTroubleshooting"]] for generic Tomcat related issues.
280
281 == MySQL ==
282
283 See [[MySQL Installation>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationMySQL||anchor="HTroubleshooting"]] for generic MySQL related issues.
284
285 == PostgreSQL ==
286
287 See [[PostgreSQL Installation>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationPostgreSQL||anchor="HTroubleshooting"]] for generic PostgreSQL related issues.
288
289 = Other useful info =
290
291 == XWiki as root webapp (short URLs) ==
292
293 Note that this section is only the part of Short URL specific to the Debian setup, for the rest you will have to look at [[the generic documentation>>doc:Documentation.AdminGuide.ShortURLs.WebHome]].
294
295 === For Tomcat 9 ===
296
297 {{warning}}
298 When doing it make sure to check after upgrade if all is OK in /etc/tomcat9/Catalina/localhost folder (xwiki.xml might be restored).
299 {{/warning}}
300
301 * Rename file ##/etc/tomcat9/Catalina/localhost/xwiki.xml## into ##/etc/tomcat9/Catalina/localhost/ROOT.xml##
302 * Edit file ##/etc/xwiki/xwiki-tomcat9.xml## and modify ##Context## XML element path from ##/xwiki## to ##/## as in moving from(((
303 {{code language="xml"}}
304 <Context path="/xwiki" docBase="/usr/lib/xwiki"
305 containerSciFilter="org.apache.tomcat.websocket.server.WsSci|org.apache.jasper.servlet.JasperInitializer">
306 {{/code}}
307
308 to
309
310 {{code language="xml"}}
311 <Context path="/" docBase="/usr/lib/xwiki"
312 containerSciFilter="org.apache.tomcat.websocket.server.WsSci|org.apache.jasper.servlet.JasperInitializer">
313 {{/code}}
314 )))
315 * Edit file ##/etc/xwiki/xwiki.cfg## and uncomment {{code language="properties"}}xwiki.webapppath={{/code}}
316
317 == Integrate with LibreOffice ==
318
319 Install libreoffice with {{code language="none"}}sudo apt-get install libreoffice{{/code}}.
320
321 And setup XWiki to automatically start and access libreoffice in ##/etc/xwiki/xwiki.properties##:
322
323 {{code language="properties"}}
324 openoffice.autoStart=true
325 openoffice.homePath=/usr/lib/libreoffice/
326 {{/code}}
327
328 See [[Office Importer Application>>extensions:Extension.Office Importer Application]] for more details.
329
330 == Standalone Solr setup ==
331
332 Take a look at [[Solr documentation>>https://lucene.apache.org/solr/guide/8_1/taking-solr-to-production.html#taking-solr-to-production]] to install it.
333
334 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).
335
336 = Overview of the important files =
337
338 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.
339
340 == XWiki ==
341
342 The configuration: **/etc/xwiki/**
343
344 * hibernate.cfg.xml //Hibernate configuration, helping to configure the database resources//
345 * xwiki.cfg
346 * xwiki.properties
347 * xwiki-tomcat9-systemd.conf // Injected trough ##/etc/systemd/system/tomcat9.service.d/xwiki-tomcat-systemd.conf##// in the tomcat9 service configuration
348 * xwiki-tomcat<version> // The Tomcat integration linked from ##/etc/tomcat<version>/Catalina/localhost##//
349
350 The permanent directory: **/var/lib/xwiki/data**
351
352 The home directory: **/usr/lib/xwiki/**
353
354 * META-INF
355 * resources
356 * skins
357 * templates
358 * WEB-INF
359 ** hibernate.cfg.xml -> /etc/xwiki/hibernate.cfg.xml
360 ** xwiki.cfg -> /etc/xwiki/xwiki.cfg
361 ** xwiki.properties -> /etc/xwiki/xwiki.properties
362
363 == Tomcat ==
364
365 **/etc/tomcat##<version>##/**
366
367 * context.xml
368 * logging.properties
369 * server.xml
370 * tomcat-users.xml
371 * web.xml
372
373 **/etc/default/**
374
375 * tomcat##<version>## //This file helps configuring the Tomcat daemon. Every change needs a restart to be effective//
376
377 **/etc/init.d/**
378
379 * tomcat##<version>## //Daemon start/stop script//
380
381 **/var/lib/tomcat##<version>##/**
382
383 * common
384 * conf -> /etc/tomcat##<version>##
385 * logs -> ../../log/tomcat##<version>     //Note that starting Debian 10 and Ubuntu 18.04 systemd service log is used//##
386 * server
387 * shared
388 * webapps
389
390 **/var/log/tomcat##<version>##/**
391
392 * catalina.out //First logging file. Check this one if you're experiencing troubles with Tomcat/XWiki.//
393 * localhost.<date>.log // "Container Log file": Start of each filter and failures thereof are listed.//
394
395 == MySQL ==
396
397 **/etc/mysql/**
398
399 * debian.cnf
400 * my.cnf //Database configuration. Max_allowed_packet is the parameter you need to change to improve upload data size.// permitted.
401
402 **/var/lib/mysql/**
403
404 * mysql
405 * xwiki //This is the xwiki database. You may want to backup this directory from time to time.//
406
407 **/var/log/**
408
409 * syslog
410 * mysql
411 ** error.log
412
413 == PostgreSQL ==
414
415 **/etc/postgresql/**
416
417 * ##<version>##
418 ** main
419 *** postgresql.conf
420 *** pg_hba.conf
421
422 **/var/lib/postgresql/##<version>##/main/**
423
424 * 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