Version 157.1 by Thomas Mortagne on 2020/01/02

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-mysql-common - XWiki MySQL common package, you can install this if you want to take care yourself of the application server
46 * xwiki-pgsql-common - XWiki PostgreSQL common package, you can install this if you want to take care yourself of the application server
47 * xwiki-tomcat8-common - XWiki Tomcat 8 common package, you can install this if you want to take care yourself of the database link
48 * xwiki-tomcat9-common - XWiki Tomcat 9 common package, you can install this if you want to take care yourself of the database link
49 * xwiki-tomcat8-mysql - XWiki Tomcat 8/MySQL based package
50 * xwiki-tomcat9-mysql - XWiki Tomcat 9/MySQL based package
51 * xwiki-tomcat8-pgsql - XWiki Tomcat 8/PostgreSQL
52 * xwiki-tomcat9-pgsql - XWiki Tomcat 9/PostgreSQL
53 * xwiki-solr-data - A pre configured Solr core to be used to setup a standalone instance of Solr for XWiki
54
55 Plus legacy packages from older versions of XWiki like xwiki-enterprise-* packages or for unsupported versions of Tomcat.
56
57 {{error}}
58 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.)
59 {{/error}}
60
61 {{info}}
62 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.
63 {{/info}}
64
65 {{warning}}
66 On Ubuntu you will need [[##universe## repository>>https://help.ubuntu.com/community/Repositories/CommandLine]] to install Tomcat packages. It's generally enabled by default.
67 {{/warning}}
68
69 = Java 8 =
70
71 XWiki require Java 8 since XWiki 8.1, **OpenJDK 8** will be automatically installed as dependency on recent distributions.
72
73 {{warning}}
74 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
75 {{/warning}}
76
77 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.
78
79 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"]].
80
81 Here is a few helpers for specific distributions:
82
83 == Ubuntu 14.04 (Trusty Tahr), Debian < 9 ==
84
85 * AdoptOpenJDK provide a Debian repository to install OpenJDK, see https://adoptopenjdk.net/installation.html#linux-pkg
86
87 = Complete Installation =
88
89 {{warning}}
90 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.
91 {{/warning}}
92
93 == Using MySQL ==
94
95 You only have to run this command to install all the interesting components.
96
97 {{code language="bash"}}
98 sudo apt-get install xwiki-tomcat9-mysql
99 {{/code}}
100
101 This package depends on xwiki-common, xwiki-tomcat9-common, xwiki-mysql-common, mysql-server, tomcat9 and libmysql-java. You might have to select a different version of Tomcat depending on what's available in your system repository.
102
103 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.
104 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.
105
106 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.
107
108 The installation now ends, with the automatic start of tomcat daemon ("Starting Tomcat servlet engine tomcat9 [OK]").
109
110 {{warning}}
111 Note that your wiki is absolutely empty, like a WAR installation. Distribution Wizard will take care of the rest.
112 {{/warning}}
113
114 == Using PostgreSQL ==
115
116 It's as simple as the MySQL installation, you only need to choose the right virtual package.
117
118 {{code language="bash"}}
119 sudo apt-get install xwiki-tomcat9-pgsql
120 {{/code}}
121
122 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##
123
124 PostgreSQL is slightly different than MySQL in the handling of databases and in the manual configuration, but everything should work on the first try.
125
126 == Security settings ==
127
128 1. (((
129 Open ##/etc/xwiki/xwiki.cfg## file and change lines:
130
131 {{code language="none"}}
132 ...
133 #-# Cookie encryption keys. You SHOULD replace these values with any random string,
134 #-# as long as the length is the same.
135 xwiki.authentication.validationKey=your1stkeyhere
136 xwiki.authentication.encryptionKey=your2ndkeyhere
137 ...
138 {{/code}}
139 )))
140 1. (((
141 If you need, add password to the built-in superadmin account, by changing line:
142
143 {{code language="none"}}
144 ...
145 #-# Enable to allow superadmin. It is disabled by default as this could be a
146 #-# security breach if it were set and you forgot about it. Should only be enabled
147 #-# for recovering the Wiki when the rights are completely messed.
148 xwiki.superadminpassword=yourpassword
149 ...
150 {{/code}}
151 )))
152
153 == Tomcat Usability ==
154
155 You can find various generic advices and troubleshooting related to Tomcat on https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Installation/InstallationWAR/InstallationTomcat/.
156
157 === Java Version ===
158
159 Make sure Tomcat is executed with the right [[Java version>>platform:AdminGuide.Installation||anchor="HHardwareandSoftwarerequirements"]].
160
161 This is usually indicated in the file ##/etc/default/tomcat8## (or ##/etc/default/tomcat7## for Tomcat 7, etc).
162
163 === Memory ===
164
165 The default Tomcat memory setup is too low for XWiki's needs.
166
167 You can change it in the file ##/etc/default/tomcat8## (or ##/etc/default/tomcat7## for Tomcat 7, etc).
168
169 Modify the property ##JAVA_OPTS##. For example:
170
171 {{code language="none"}}
172 JAVA_OPTS="-Djava.awt.headless=true -Xmx1024m"
173 {{/code}}
174
175 You should [[check the Memory settings we recommend>>platform:AdminGuide.Performances||anchor="HMemory"]].
176
177 === /dev/urandom ===
178
179 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:
180
181 * edit ##/etc/default/tomcat8## file and add
182
183 {{code language="bash"}}
184 JAVA_OPTS="${JAVA_OPTS} -Djava.security.egd=file:/dev/./urandom"
185 {{/code}}
186
187 = Concluding Step =
188
189 {{include reference="Documentation.AdminGuide.Installation.InstallationConcludingSteps.WebHome"/}}
190
191 = Uninstallation =
192
193 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:
194
195 {{code language="bash"}}
196 sudo apt-get --purge remove xwiki-common
197 {{/code}}
198
199 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
200
201 {{code language="bash"}}
202 sudo apt-get --purge autoremove
203 {{/code}}
204
205 = Troubleshooting =
206
207 d
208
209 == My wiki is empty after upgrading a Tomcat9 based package ==
210
211 === Upgrading from another Tomcat 9 based package ===
212
213 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).
214
215 You will need to find where was the data stored and move it to ##/var/lib/xwiki/data##.
216
217 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".
218
219 === Previous from a package based on a version of Tomcat lower than 9 ===
220
221 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.
222
223 The workaround is to execute the following commands:
224
225 * {{code language="sh"}}mkdir /etc/systemd/system/tomcat9.service.d/{{/code}}
226 * {{code language="sh"}}echo -e "[Service]\nReadWritePaths=/var/lib/xwiki/data" > /etc/systemd/system/tomcat9.service.d/override.conf{{/code}}
227 * {{code language="sh"}}systemctl daemon-reload{{/code}}
228 * {{code language="sh"}}systemctl restart tomcat9.service{{/code}}
229
230 == Tomcat ==
231
232 See [[Tomcat Installation>>platform:AdminGuide.InstallationTomcat||anchor="HTroubleshooting"]] for generic Tomcat related issues.
233
234 === Ubuntu 16.04 (Xenial Xerus) ===
235
236 At time of writing the version of Tomcat provide by Ubuntu 16.04 repository has a serious classloader related bug which makes impossible to use code macro or write Python scripts in XWiki. See https://bugs.launchpad.net/ubuntu/+source/tomcat8/+bug/1644144 and https://forum.xwiki.org/t/code-macro-requirements/909/20 for some more detailed explanations and workarounds.
237
238 {{code language="bash"}}
239 sudo add-apt-repository ppa:nacc/tomcat8v2
240 sudo apt-get update
241 sudo apt-get install tomcat8=8.0.32-1ubuntu1.3~ppa2
242 sudo apt-get install tomcat8-common=8.0.32-1ubuntu1.3~ppa2
243 sudo apt-get install libtomcat8-java=8.0.32-1ubuntu1.3~ppa2
244 sudo service tomcat8 restart
245 {{/code}}
246
247 Don't hesitate to click on "This bug affects me" on launchpad page if it's still not fixed, might help speeding up things...
248
249 == MySQL ==
250
251 See [[MySQL Installation>>platform:AdminGuide.InstallationMySQL||anchor="HTroubleshooting"]] for generic MySQL related issues.
252
253 == PostgreSQL ==
254
255 See [[PostgreSQL Installation>>platform:AdminGuide.InstallationPostgreSQL||anchor="HTroubleshooting"]] for generic PostgreSQL related issues.
256
257 === Bad version of PostgreSQL driver on Debian Wheezy ===
258
259 The version of the PostgreSQL driver on Debian Wheezy is the 9.1 (at least when writing those lines) which does not work well with XWiki. You will have to upgrade it.
260
261 The latest JDBC postgres driver is available at https://jdbc.postgresql.org/download.html , at the time of this writing, the latest version is postgresql-9.4-1201.jdbc41.jar (which works fine with xwiki), you need to download the driver to your server, a good place is where the other drivers are: /usr/share/java, then remove the symlink postgresql-jdbc4.jar and replace it by one to the new driver:
262
263 {{code}}
264 wget -O /usr/share/java/postgresql-9.4-1201.jdbc41.jar https://jdbc.postgresql.org/download/postgresql-9.4-1201.jdbc41.jar
265 rm /usr/share/java/postgresql-jdbc4.jar
266 ln -s /usr/share/java/postgresql-9.4-1201.jdbc41.jar /usr/share/java/postgresql-jdbc4.jar
267 {{/code}}
268
269 Restart tomcat and you will not have any issue with the JDBC driver.
270
271 == XWiki won't start and I get Solr related error(s) in the log ==
272
273 There is no automatic migration of Solr schema and it changes from time to time. The simplest fix in such case is usually to stop Tomcat, delete the folder ##/var/lib/xwiki/data/solr## and restart Tomcat. XWiki will automatically create a new one and start indexing the wiki.
274
275 {{code language="bash"}}
276 sudo /etc/init.d/tomcat8 stop
277 rm -rf /var/lib/xwiki/data/solr
278 sudo /etc/init.d/tomcat8 start
279 {{/code}}
280
281 = Other useful info =
282
283 == XWiki as root webapp (short URLs) ==
284
285 {{warning}}
286 When doing it make sure to check after upgrade if all is OK in /etc/tomcat8/Catalina/localhost folder (xwiki.xml might be restored).
287 {{/warning}}
288
289 * Rename file ##/etc/tomcat7/Catalina/localhost/xwiki.xml## into ##/etc/tomcat8/Catalina/localhost/ROOT.xml##
290 * Edit file ##/etc/xwiki/xwiki-tomcat8.xml## (or ##/etc/xwiki/xwiki-tomcat7.xml## depending on your tomcat version) and modify ##Context## XML element path from ##/xwiki## to ##/## as in moving from(((
291 {{code language="xml"}}
292 <Context path="/xwiki" docBase="/usr/lib/xwiki" privileged="true" allowLinking="true" crossContext="true">
293 <!-- make symlinks work in Tomcat -->
294 <Resources className="org.apache.naming.resources.FileDirContext" allowLinking="true" />
295 </Context>
296 {{/code}}
297
298 to
299
300 {{code language="xml"}}
301 <Context path="/" docBase="/usr/lib/xwiki" privileged="true" allowLinking="true" crossContext="true">
302 <!-- make symlinks work in Tomcat -->
303 <Resources className="org.apache.naming.resources.FileDirContext" allowLinking="true" />
304 </Context>
305 {{/code}}
306 )))
307 * Edit file ##/etc/xwiki/xwiki.cfg## and uncomment {{code language="properties"}}xwiki.webapppath={{/code}}
308
309 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]].
310
311 == Integrate with LibreOffice ==
312
313 Install libreoffice with {{code language="none"}}sudo apt-get install libreoffice{{/code}}.
314
315 And setup XWiki to automatically start and access libreoffice in ##/etc/xwiki/xwiki.properties##:
316
317 {{code language="properties"}}
318 openoffice.autoStart=true
319 openoffice.homePath=/usr/lib/libreoffice/
320 {{/code}}
321
322 See [[Office Importer Application>>extensions:Extension.Office Importer Application]] for more details.
323
324 = Overview of the important files =
325
326 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.
327
328 == XWiki ==
329
330 The configuration: **/etc/xwiki/**
331
332 * hibernate.cfg.xml //Hibernate configuration, helping to configure the database resources//
333 * xwiki.cfg
334 * xwiki.properties
335 * xwiki-tomcat9-systemd.conf //Injected trough ##/etc/systemd/system/tomcat9.service.d/xwiki-tomcat-systemd.conf##// in the tomcat9 service configuration
336
337 The permanent directory: **/var/lib/xwiki/data**
338
339 The home directory: **/usr/lib/xwiki/**
340
341 * META-INF
342 * resources
343 * skins
344 * templates
345 * WEB-INF
346 ** hibernate.cfg.xml -> /etc/xwiki/hibernate.cfg.xml
347 ** xwiki.cfg -> /etc/xwiki/xwiki.cfg
348 ** xwiki.properties -> /etc/xwiki/xwiki.properties
349
350 == Tomcat ==
351
352 **/etc/tomcat##<version>##/**
353
354 * context.xml
355 * logging.properties
356 * server.xml
357 * tomcat-users.xml
358 * web.xml
359
360 **/etc/default/**
361
362 * tomcat##<version>## //This file helps configuring the Tomcat daemon. Every change needs a restart to be effective//
363
364 **/etc/init.d/**
365
366 * tomcat##<version>## //Daemon start/stop script//
367
368 **/var/lib/tomcat##<version>##/**
369
370 * common
371 * conf -> /etc/tomcat##<version>##
372 * logs -> ../../log/tomcat##<version>##
373 * server
374 * shared
375 * webapps
376
377 **/var/log/tomcat##<version>##/**
378
379 * catalina.out //First logging file. Check this one if you're experiencing troubles with Tomcat/XWiki.//
380 * localhost.<date>.log // "Container Log file": Start of each filter and failures thereof are listed.//
381
382 == MySQL ==
383
384 **/etc/mysql/**
385
386 * debian.cnf
387 * my.cnf //Database configuration. Max_allowed_packet is the parameter you need to change to improve upload data size.// permitted.
388
389 **/var/lib/mysql/**
390
391 * mysql
392 * xwiki //This is the xwiki database. You may want to backup this directory from time to time.//
393
394 **/var/log/**
395
396 * syslog
397 * mysql
398 ** error.log
399
400 == PostgreSQL ==
401
402 **/etc/postgresql/**
403
404 * ##<version>##
405 ** main
406 *** postgresql.conf
407 *** pg_hba.conf
408
409 **/var/lib/postgresql/##<version>##/main/**
410
411 * base

Get Connected