Version 141.1 by Thomas Mortagne on 2019/03/18

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 Before you start, make sure you've checked the [[System Requirements>>platform:AdminGuide.Installation||anchor="HPrerequisites"]]. The most important step is to have a Java JRE installed.
10
11 = APT Configuration =
12
13 First, you have to configure your package manager in order to use xwiki's repository. This can be done simply, using this command:
14
15 {{code language="bash"}}
16 wget -q "https://maven.xwiki.org/public.gpg" -O- | sudo apt-key add -
17 sudo wget "https://maven.xwiki.org/stable/xwiki-stable.list" -P /etc/apt/sources.list.d/
18 {{/code}}
19
20 {{info}}
21 Note that there is several repositories you can choose (as alternatives to the stable one you have in the previous example):
22
23 * [[https://maven.xwiki.org/releases/xwiki-releases.list]]: all released versions including milestones and release candidates (beta)
24 * [[https://maven.xwiki.org/stable/xwiki-stable.list]]: all released versions excluding milestones and release candidates (stable)
25 * [[https://maven.xwiki.org/lts/xwiki-lts.list]]: the current "long term support" branch versions as defined in [[Support page>>xwiki:Main.Support]]
26 {{/info}}
27
28 Now you can update the packages database to read the data from this repository.
29
30 {{code language="bash"}}
31 sudo apt-get update
32 {{/code}}
33
34 {{info}}
35 I'll assume you're using APT tools. You can use Aptitude as well.
36 {{/info}}
37
38 Now you can make a little search to see what this repo offers.
39
40 {{code language="bash"}}
41 apt-cache search xwiki
42 {{/code}}
43
44 It shows the following packages (the exact list depends on the version the repository contains):
45
46 * xwiki-common - XWiki, you can install this if you want to take care yourself of the database and application server
47 * xwiki-mysql-common - XWiki MySQL common package, you can install this if you want to take care yourself of the application server
48 * xwiki-pgsql-common - XWiki PostgreSQL common package, you can install this if you want to take care yourself of the application server
49 * xwiki-tomcat7-common - XWiki Tomcat 7 common package, you can install this if you want to take care yourself of the database link
50 * xwiki-tomcat8-common - XWiki Tomcat 8 common package, you can install this if you want to take care yourself of the database link
51 * xwiki-tomcat7-mysql - XWiki Tomcat 7/MySQL based package
52 * xwiki-tomcat8-mysql - XWiki Tomcat 8/MySQL based package
53 * xwiki-tomcat7-pgsql - XWiki Tomcat 7/PostgreSQL
54 * xwiki-tomcat8-pgsql - XWiki Tomcat 8/PostgreSQL
55 * xwiki-solr-data - A pre configured Solr core to be used to setup a standalone instance of Solr for XWiki
56
57 Plus legacy packages from older versions of XWiki like xwiki-enterprise-* packages.
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 = Java 8 =
72
73 XWiki require Java 8 since XWiki 8.1, **OpenJDK 8** will be automatically installed as dependency on recent distributions.
74
75 {{warning}}
76 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
77 {{/warning}}
78
79 You can also use Web Upd8 repository if you want **Oracle Java** version. See documentation for [[Ubuntu>>http://www.webupd8.org/2012/09/install-oracle-java-8-in-ubuntu-via-ppa.html]] or [[Debian>>http://www.webupd8.org/2014/03/how-to-install-oracle-java-8-in-debian.html]].
80
81 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.
82
83 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"]].
84
85 Here is a few helpers for specific distributions:
86
87 == Ubuntu 14.04 (Trusty Tahr) ==
88
89 * Web Upd8 provide a ppa with Oracle JVMs on it, see http://www.webupd8.org/2012/09/install-oracle-java-8-in-ubuntu-via-ppa.html
90
91 == Debian 7 (Wheezy) or 8 (Jessie) ==
92
93 * for OpenJDK 8 you can enable backports repository: see https://backports.debian.org/Instructions/
94 * Web Upd8 provide a Debian repository with Oracle JVMs on it, see http://www.webupd8.org/2014/03/how-to-install-oracle-java-8-in-debian.html
95
96 = Complete Installation =
97
98 {{warning}}
99 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.
100 {{/warning}}
101
102 == Using MySQL ==
103
104 You only have to run this command to install all the interesting components.
105
106 {{code language="bash"}}
107 sudo apt-get install xwiki-tomcat8-mysql
108 {{/code}}
109
110 This package depends on xwiki-common, xwiki-tomcat8-common, xwiki-mysql-common, mysql-server, tomcat8 and libmysql-java.
111
112 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.
113 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.
114
115 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.
116
117 The installation now ends, with the automatic start of tomcat daemon ("Starting Tomcat servlet engine tomcat7 [OK]").
118
119 {{warning}}
120 Note that your wiki is absolutely empty, like a WAR installation. Distribution Wizard will take care of the rest.
121 {{/warning}}
122
123 == Using PostgreSQL ==
124
125 It's as simple as the MySQL installation, you only need to choose the right virtual package.
126
127 {{code language="bash"}}
128 sudo apt-get install xwiki-tomcat8-pgsql
129 {{/code}}
130
131 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##
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 == Security settings ==
136
137 1. (((
138 Open ##/etc/xwiki/xwiki.cfg## file and change lines:
139
140 {{code language="none"}}
141 ...
142 #-# Cookie encryption keys. You SHOULD replace these values with any random string,
143 #-# as long as the length is the same.
144 xwiki.authentication.validationKey=your1stkeyhere
145 xwiki.authentication.encryptionKey=your2ndkeyhere
146 ...
147 {{/code}}
148 )))
149 1. (((
150 If you need, add password to the built-in superadmin account, by changing line:
151
152 {{code language="none"}}
153 ...
154 #-# Enable to allow superadmin. It is disabled by default as this could be a
155 #-# security breach if it were set and you forgot about it. Should only be enabled
156 #-# for recovering the Wiki when the rights are completely messed.
157 xwiki.superadminpassword=yourpassword
158 ...
159 {{/code}}
160 )))
161
162 == Tomcat Usability ==
163
164 === Java Version ===
165
166 Make sure Tomcat is executed with the right [[Java version>>platform:AdminGuide.Installation||anchor="HHardwareandSoftwarerequirements"]].
167
168 This is usually indicated in the file ##/etc/default/tomcat8## (or ##/etc/default/tomcat7## for Tomcat 7, etc).
169
170 === Memory ===
171
172 The default Tomcat memory setup is too low for XWiki's needs.
173
174 You can change it in the file ##/etc/default/tomcat8## (or ##/etc/default/tomcat7## for Tomcat 7, etc).
175
176 Modify the property ##JAVA_OPTS##. For example:
177
178 {{code language="none"}}
179 JAVA_OPTS="-Djava.awt.headless=true -Xmx1024m"
180 {{/code}}
181
182 You should [[check the Memory settings we recommend>>platform:AdminGuide.Performances||anchor="HMemory"]].
183
184 === /dev/urandom ===
185
186 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:
187
188 * edit ##/etc/defaualt/tomcat8## file and add
189
190 {{code language="bash"}}
191 JAVA_OPTS="${JAVA_OPTS} -Dsecurerandom.source=file:/dev/urandom"
192 {{/code}}
193
194 === More ===
195
196 You can find more Tomcat related advice and troubleshooting on https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Installation/InstallationWAR/InstallationTomcat/.
197
198 = Concluding Step =
199
200 {{include reference="Documentation.AdminGuide.Installation.InstallationConcludingSteps.WebHome"/}}
201
202 = Uninstallation =
203
204 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:
205
206 {{code language="bash"}}
207 sudo apt-get --purge remove xwiki-common
208 {{/code}}
209
210 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
211
212 {{code language="bash"}}
213 sudo apt-get --purge autoremove
214 {{/code}}
215
216 = Troubleshooting =
217
218 == Tomcat ==
219
220 See [[Tomcat Installation>>platform:AdminGuide.InstallationTomcat||anchor="HTroubleshooting"]] for generic Tomcat related issues.
221
222 === Ubuntu 16.04 (Xenial Xerus) ===
223
224 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.
225
226 {{code language="bash"}}
227 sudo add-apt-repository ppa:nacc/tomcat8v2
228 sudo apt-get update
229 sudo apt-get install tomcat8=8.0.32-1ubuntu1.3~ppa2
230 sudo apt-get install tomcat8-common=8.0.32-1ubuntu1.3~ppa2
231 sudo apt-get install libtomcat8-java=8.0.32-1ubuntu1.3~ppa2
232 sudo service tomcat8 restart
233 {{/code}}
234
235 Don't hesitate to click on "This bug affects me" on launchpad page if it's still not fixed, might help speeding up things...
236
237 == MySQL ==
238
239 See [[MySQL Installation>>platform:AdminGuide.InstallationMySQL||anchor="HTroubleshooting"]] for generic MySQL related issues.
240
241 == PostgreSQL ==
242
243 See [[PostgreSQL Installation>>platform:AdminGuide.InstallationPostgreSQL||anchor="HTroubleshooting"]] for generic PostgreSQL related issues.
244
245 === Bad version of PostgreSQL driver on Debian Wheezy ===
246
247 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.
248
249 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:
250
251 {{code}}
252 wget -O /usr/share/java/postgresql-9.4-1201.jdbc41.jar https://jdbc.postgresql.org/download/postgresql-9.4-1201.jdbc41.jar
253 rm /usr/share/java/postgresql-jdbc4.jar
254 ln -s /usr/share/java/postgresql-9.4-1201.jdbc41.jar /usr/share/java/postgresql-jdbc4.jar
255 {{/code}}
256
257 Restart tomcat and you will not have any issue with the JDBC driver.
258
259 == XWiki won't start and I get Solr related error(s) in the log ==
260
261 There is no automatic migration of Solr schema and it changes it from time to time. The simplest fix 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.
262
263 {{code language="bash"}}
264 sudo /etc/init.d/tomcat8 stop
265 rm -rf /var/lib/xwiki/data/solr
266 sudo /etc/init.d/tomcat8 start
267 {{/code}}
268
269 = Other useful info =
270
271 == XWiki as root webapp (short URLs) ==
272
273 {{warning}}
274 When doing it make sure to check after upgrade if all is OK in /etc/tomcat8/Catalina/localhost folder (xwiki.xml might be restored).
275 {{/warning}}
276
277 * Rename file ##/etc/tomcat7/Catalina/localhost/xwiki.xml## into ##/etc/tomcat8/Catalina/localhost/ROOT.xml##
278 * 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(((
279 {{code language="xml"}}
280 <Context path="/xwiki" docBase="/usr/lib/xwiki" privileged="true" allowLinking="true" crossContext="true">
281 <!-- make symlinks work in Tomcat -->
282 <Resources className="org.apache.naming.resources.FileDirContext" allowLinking="true" />
283 </Context>
284 {{/code}}
285
286 to
287
288 {{code language="xml"}}
289 <Context path="/" docBase="/usr/lib/xwiki" privileged="true" allowLinking="true" crossContext="true">
290 <!-- make symlinks work in Tomcat -->
291 <Resources className="org.apache.naming.resources.FileDirContext" allowLinking="true" />
292 </Context>
293 {{/code}}
294 )))
295 * Edit file ##/etc/xwiki/xwiki.cfg## and uncomment {{code language="properties"}}xwiki.webapppath={{/code}}
296
297 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]].
298
299 == Integrate with LibreOffice ==
300
301 Install libreoffice with {{code language="none"}}sudo apt-get install libreoffice{{/code}}.
302
303 And setup XWiki to automatically start and access libreoffice in ##/etc/xwiki/xwiki.properties##:
304
305 {{code language="properties"}}
306 openoffice.autoStart=true
307 openoffice.homePath=/usr/lib/libreoffice/
308 {{/code}}
309
310 See [[Office Importer Application>>extensions:Extension.Office Importer Application]] for more details.
311
312 = Overview of the important files =
313
314 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.
315
316 == XWiki ==
317
318 **/etc/xwiki/**
319
320 * hibernate.cfg.xml //Hibernate configuration, helping to configure the database resources//
321 * xwiki.cfg
322 * xwiki.properties
323
324 **/usr/lib/xwiki/**
325
326 * META-INF
327 * resources
328 * skins
329 * templates
330 * WEB-INF
331 ** hibernate.cfg.xml -> /etc/xwiki/hibernate.cfg.xml
332 ** xwiki.cfg -> /etc/xwiki/xwiki.cfg
333 ** xwiki.properties -> /etc/xwiki/xwiki.properties
334
335 == Tomcat ==
336
337 **/etc/tomcat##<version>##/**
338
339 * context.xml
340 * logging.properties
341 * server.xml
342 * tomcat-users.xml
343 * web.xml
344
345 **/etc/default/**
346
347 * tomcat##<version>## //This file helps configuring the Tomcat daemon. Every change needs a restart to be effective//
348
349 **/etc/init.d/**
350
351 * tomcat##<version>## //Daemon start/stop script//
352
353 **/var/lib/tomcat##<version>##/**
354
355 * common
356 * conf -> /etc/tomcat##<version>##
357 * logs -> ../../log/tomcat##<version>##
358 * server
359 * shared
360 * webapps
361
362 **/var/log/tomcat##<version>##/**
363
364 * catalina.out //First logging file. Check this one if you're experiencing troubles with Tomcat/XWiki.//
365 * localhost.<date>.log // "Container Log file": Start of each filter and failures thereof are listed.//
366
367 == MySQL ==
368
369 **/etc/mysql/**
370
371 * debian.cnf
372 * my.cnf //Database configuration. Max_allowed_packet is the parameter you need to change to improve upload data size.// permitted.
373
374 **/var/lib/mysql/**
375
376 * mysql
377 * xwiki //This is the xwiki database. You may want to backup this directory from time to time.//
378
379 **/var/log/**
380
381 * syslog
382 * mysql
383 ** error.log
384
385 == PostgreSQL ==
386
387 **/etc/postgresql/**
388
389 * ##<version>##
390 ** main
391 *** postgresql.conf
392 *** pg_hba.conf
393
394 **/var/lib/postgresql/##<version>##/main/**
395
396 * base

Get Connected