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]]: all released versions including milestones and release candidates (beta)
22 * [[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]]: 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 {{info}}
33 I'll assume you're using APT tools. You can use Aptitude as well.
34 {{/info}}
35
36 Now you can make a little search to see what this repo offers.
37
38 {{code language="bash"}}
39 apt-cache search xwiki
40 {{/code}}
41
42 It shows the following packages (the exact list depends on the version the repository contains):
43
44 * xwiki-common - XWiki, you can install this if you want to take care yourself of the database and 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 * xwiki-tomcat8-common - XWiki Tomcat 8 common package, you can install this if you want to take care yourself of the database link
49 * xwiki-tomcat9-common - XWiki Tomcat 9 common package, you can install this if you want to take care yourself of the database link
50 * xwiki-tomcat8-mariadb - XWiki Tomcat 8/MariaDB based package
51 * xwiki-tomcat9-mariadb - XWiki Tomcat 9/MariaDB based package
52 * xwiki-tomcat8-mysql - XWiki Tomcat 8/MySQL based package
53 * xwiki-tomcat9-mysql - XWiki Tomcat 9/MySQL based package
54 * xwiki-tomcat8-pgsql - XWiki Tomcat 8/PostgreSQL
55 * xwiki-tomcat9-pgsql - XWiki Tomcat 9/PostgreSQL
56 * xwiki-solr-data - A pre configured Solr core to be used to setup a standalone instance of Solr for XWiki
57
58 Plus legacy packages from older versions of XWiki like xwiki-enterprise-* packages or for unsupported versions of Tomcat.
59
60 {{error}}
61 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.)
62 {{/error}}
63
64 {{info}}
65 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.
66 {{/info}}
67
68 {{warning}}
69 On Ubuntu you will need [[##universe## repository>>https://help.ubuntu.com/community/Repositories/CommandLine]] to install Tomcat packages. It's generally enabled by default.
70 {{/warning}}
71
72 = Java 8 =
73
74 XWiki require Java 8 since XWiki 8.1, **OpenJDK 8** will be automatically installed as dependency on recent distributions.
75
76 {{warning}}
77 In some cases Java 11 might be installed and activated by default. If you have both Java version (8 and 11) in your distribution, you can modify ##/etc/default/tomcat8## to point to a java8 JAVA_HOME
78 {{/warning}}
79
80 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.
81
82 Also if you have several versions of Java installed you might need to explicitly tell Tomcat which one to use after the install. See [[Tomcat Usability section>>||anchor="HJavaVersion"]].
83
84 Here is a few helpers for specific distributions:
85
86 == Ubuntu 14.04 (Trusty Tahr), Debian < 9 ==
87
88 * AdoptOpenJDK provide a Debian repository to install OpenJDK, see https://adoptopenjdk.net/installation.html#linux-pkg
89
90 = Complete Installation =
91
92 {{warning}}
93 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.
94 {{/warning}}
95
96 == Using MySQL ==
97
98 You only have to run this command to install all the interesting components.
99
100 {{code language="bash"}}
101 sudo apt-get install xwiki-tomcat9-mysql
102 {{/code}}
103
104 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.
105
106 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.
107 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.
108
109 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.
110
111 The installation now ends, with the automatic start of tomcat daemon ("Starting Tomcat servlet engine tomcat9 [OK]").
112
113 {{warning}}
114 Note that your wiki is absolutely empty, like a WAR installation. Distribution Wizard will take care of the rest.
115 {{/warning}}
116
117 == Using MariaDB ==
118
119 You only have to run this command to install all the interesting components.
120
121 {{code language="bash"}}
122 sudo apt-get install xwiki-tomcat9-mariadb
123 {{/code}}
124
125 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.
126
127 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.
128 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.
129
130 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.
131
132 The installation now ends, with the automatic start of tomcat daemon ("Starting Tomcat servlet engine tomcat9 [OK]").
133
134 {{warning}}
135 Note that your wiki is absolutely empty, like a WAR installation. Distribution Wizard will take care of the rest.
136 {{/warning}}
137
138 == Using PostgreSQL ==
139
140 It's as simple as the MySQL installation, you only need to choose the right virtual package.
141
142 {{code language="bash"}}
143 sudo apt-get install xwiki-tomcat9-pgsql
144 {{/code}}
145
146 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##
147
148 PostgreSQL is slightly different than MySQL in the handling of databases and in the manual configuration, but everything should work on the first try.
149
150 == Security settings ==
151
152 1. (((
153 Open ##/etc/xwiki/xwiki.cfg## file and change lines:
154
155 {{code language="none"}}
156 ...
157 #-# Cookie encryption keys. You SHOULD replace these values with any random string,
158 #-# as long as the length is the same.
159 xwiki.authentication.validationKey=your1stkeyhere
160 xwiki.authentication.encryptionKey=your2ndkeyhere
161 ...
162 {{/code}}
163 )))
164 1. (((
165 If you need, add password to the built-in superadmin account, by changing line:
166
167 {{code language="none"}}
168 ...
169 #-# Enable to allow superadmin. It is disabled by default as this could be a
170 #-# security breach if it were set and you forgot about it. Should only be enabled
171 #-# for recovering the Wiki when the rights are completely messed.
172 xwiki.superadminpassword=yourpassword
173 ...
174 {{/code}}
175 )))
176
177 == Tomcat Usability ==
178
179 You can find [[various generic advices and troubleshooting related to Tomcat>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationTomcat.WebHome]].
180
181 === Java Version ===
182
183 Make sure Tomcat is executed with the right [[Java version>>platform:AdminGuide.Installation||anchor="HHardwareandSoftwarerequirements"]].
184
185 This is usually indicated in the file ##/etc/default/tomcat8## (or ##/etc/default/tomcat7## for Tomcat 7, etc).
186
187 === Memory ===
188
189 The default Tomcat memory setup is too low for XWiki's needs.
190
191 You can change it in the file ##/etc/default/tomcat8## (or ##/etc/default/tomcat7## for Tomcat 7, etc).
192
193 Modify the property ##JAVA_OPTS##. For example:
194
195 {{code language="none"}}
196 JAVA_OPTS="-Djava.awt.headless=true -Xmx1024m"
197 {{/code}}
198
199 You should [[check the Memory settings we recommend>>platform:AdminGuide.Performances||anchor="HMemory"]].
200
201 === /dev/urandom ===
202
203 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:
204
205 * edit ##/etc/default/tomcat8## file and add
206
207 {{code language="bash"}}
208 JAVA_OPTS="${JAVA_OPTS} -Djava.security.egd=file:/dev/./urandom"
209 {{/code}}
210
211 = Concluding Step =
212
213 {{include reference="Documentation.AdminGuide.Installation.InstallationConcludingSteps.WebHome"/}}
214
215 = Uninstallation =
216
217 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:
218
219 {{code language="bash"}}
220 sudo apt-get --purge remove xwiki-common
221 {{/code}}
222
223 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
224
225 {{code language="bash"}}
226 sudo apt-get --purge autoremove
227 {{/code}}
228
229 = Troubleshooting =
230
231 You can find a generic Troubleshooting section on [[https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Installation/#HTroubleshooting]].
232
233 == My wiki is empty after upgrading a Tomcat9 based package ==
234
235 === Upgrading from another Tomcat 9 based package ===
236
237 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 store in a temporary location (generally /var/cache/tomcat9/Catalina/localhost/xwiki).
238
239 You will need to find where was the data stored and move it to ##/var/lib/xwiki/data##.
240
241 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".
242
243 === Previous from a package based on a version of Tomcat lower than 9 ===
244
245 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.
246
247 The workaround is to execute the following commands:
248
249 * {{code language="sh"}}mkdir /etc/systemd/system/tomcat9.service.d/{{/code}}
250 * {{code language="sh"}}echo -e "[Service]\nReadWritePaths=/var/lib/xwiki/data" > /etc/systemd/system/tomcat9.service.d/override.conf{{/code}}
251 * {{code language="sh"}}systemctl daemon-reload{{/code}}
252 * {{code language="sh"}}systemctl restart tomcat9.service{{/code}}
253
254 == Java ==
255
256 The chart macro doesn't appear to be working with a clean install. 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 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.
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>>platform:AdminGuide.InstallationTomcat||anchor="HTroubleshooting"]] for generic Tomcat related issues.
271
272 == MySQL ==
273
274 See [[MySQL Installation>>platform:AdminGuide.InstallationMySQL||anchor="HTroubleshooting"]] for generic MySQL related issues.
275
276 == PostgreSQL ==
277
278 See [[PostgreSQL Installation>>platform:AdminGuide.InstallationPostgreSQL||anchor="HTroubleshooting"]] for generic PostgreSQL related issues.
279
280 = Other useful info =
281
282 == XWiki as root webapp (short URLs) ==
283
284 {{warning}}
285 When doing it make sure to check after upgrade if all is OK in /etc/tomcat9/Catalina/localhost folder (xwiki.xml might be restored).
286 {{/warning}}
287
288 * Rename file ##/etc/tomcat9/Catalina/localhost/xwiki.xml## into ##/etc/tomcat9/Catalina/localhost/ROOT.xml##
289 * Edit file ##/etc/xwiki/xwiki-tomcat9.xml## and modify ##Context## XML element path from ##/xwiki## to ##/## as in moving from(((
290 {{code language="xml"}}
291 <Context path="/xwiki" docBase="/usr/lib/xwiki"
292 containerSciFilter="org.apache.tomcat.websocket.server.WsSci|org.apache.jasper.servlet.JasperInitializer">
293 {{/code}}
294
295 to
296
297 {{code language="xml"}}
298 <Context path="/" docBase="/usr/lib/xwiki"
299 containerSciFilter="org.apache.tomcat.websocket.server.WsSci|org.apache.jasper.servlet.JasperInitializer">
300 {{/code}}
301 )))
302 * Edit file ##/etc/xwiki/xwiki.cfg## and uncomment {{code language="properties"}}xwiki.webapppath={{/code}}
303
304 Note that this is only the part of Short URL which is specific to the Debian setup, for the rest you will have to look at [[the generic documentation>>doc:Documentation.AdminGuide.ShortURLs.WebHome]].
305
306 == Integrate with LibreOffice ==
307
308 Install libreoffice with {{code language="none"}}sudo apt-get install libreoffice{{/code}}.
309
310 And setup XWiki to automatically start and access libreoffice in ##/etc/xwiki/xwiki.properties##:
311
312 {{code language="properties"}}
313 openoffice.autoStart=true
314 openoffice.homePath=/usr/lib/libreoffice/
315 {{/code}}
316
317 See [[Office Importer Application>>extensions:Extension.Office Importer Application]] for more details.
318
319 == Standalone Solr setup ==
320
321 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.
322
323 Then you will need to add the XWiki schema configuration. Since 12.0 the package ##xwiki-solr-core## will automatically register the XWiki core in the Solr instance (provided the default configuration was used). Before 12.0 you can use the xwiki-solr-data Debian package and add some links to register it in your Solr instance.
324
325 = Overview of the important files =
326
327 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.
328
329 == XWiki ==
330
331 The configuration: **/etc/xwiki/**
332
333 * hibernate.cfg.xml //Hibernate configuration, helping to configure the database resources//
334 * xwiki.cfg
335 * xwiki.properties
336 * xwiki-tomcat9-systemd.conf //Injected trough ##/etc/systemd/system/tomcat9.service.d/xwiki-tomcat-systemd.conf##// in the tomcat9 service configuration
337
338 The permanent directory: **/var/lib/xwiki/data**
339
340 The home directory: **/usr/lib/xwiki/**
341
342 * META-INF
343 * resources
344 * skins
345 * templates
346 * WEB-INF
347 ** hibernate.cfg.xml -> /etc/xwiki/hibernate.cfg.xml
348 ** xwiki.cfg -> /etc/xwiki/xwiki.cfg
349 ** xwiki.properties -> /etc/xwiki/xwiki.properties
350
351 == Tomcat ==
352
353 **/etc/tomcat##<version>##/**
354
355 * context.xml
356 * logging.properties
357 * server.xml
358 * tomcat-users.xml
359 * web.xml
360
361 **/etc/default/**
362
363 * tomcat##<version>## //This file helps configuring the Tomcat daemon. Every change needs a restart to be effective//
364
365 **/etc/init.d/**
366
367 * tomcat##<version>## //Daemon start/stop script//
368
369 **/var/lib/tomcat##<version>##/**
370
371 * common
372 * conf -> /etc/tomcat##<version>##
373 * logs -> ../../log/tomcat##<version>##
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

Get Connected