Installation using Debian (.DEB) packages (XWiki.org)

This distribution allows installing XWiki and every component needed for a production instance automatically.

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

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/

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

25

26

Now you can update the packages database to read the data from this repository.

sudo apt-get update

I'll assume you're using APT tools. You can use Aptitude as well.

34

35

36

Now you can make a little search to see what this repo offers.

37

38

39

apt-cache search xwiki

40

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-all - An entry point package which a dependency on all the solr core required to setup a standalone version compatible with XWiki Standard

57

* xwiki-solr-core - A pre configured Solr core for the XWiki search feature

58

* xwiki-solr-events - A pre configured Solr core for the XWiki events/notifications storage

59

* xwiki-solr-ratings - A pre configured Solr core for the XWiki rating storage

60

61

Plus legacy packages from older versions of XWiki like xwiki-enterprise-* packages or for unsupported versions of Tomcat.

62

63

64

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.)

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.

On Ubuntu you will need [[##universe## repository>>https://help.ubuntu.com/community/Repositories/CommandLine]] to install Tomcat packages. It's generally enabled by default.

= Java 8 =

XWiki require Java 8 since XWiki 8.1, **OpenJDK 11** will be automatically installed as dependency on recent distributions.

78

79

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.

80

81

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"]].

82

83

Here is a few helpers for specific distributions:

84

85

== Ubuntu 14.04 (Trusty Tahr), Debian < 9 ==

86

87

* AdoptOpenJDK provide a Debian repository to install OpenJDK, see https://adoptopenjdk.net/installation.html#linux-pkg

88

89

= Complete Installation =

90

91

92

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.

== Using MariaDB ==

Note that XWiki require at least MariaDB 5.10. If your Debian distribution provide an older version (like Debian Stretch/9) you can use the one of the repositories provided by the MariaDB project to get a more recent version on https://downloads.mariadb.org/mariadb/repositories/.

99

100

101

You only have to run this command to install all the interesting components.

102

103

104

sudo apt-get install xwiki-tomcat9-mariadb

105

106

107

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.

108

109

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.

110

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.

111

112

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.

113

114

The installation now ends, with the automatic start of tomcat daemon ("Starting Tomcat servlet engine tomcat9 [OK]").

115

116

117

Note that your wiki is absolutely empty, like a WAR installation. Distribution Wizard will take care of the rest.

== Using MySQL ==

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).

124

125

126

You only have to run this command to install all the interesting components.

127

128

129

sudo apt-get install xwiki-tomcat9-mysql

130

131

132

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.

133

134

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.

135

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.

136

137

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.

138

139

The installation now ends, with the automatic start of tomcat daemon ("Starting Tomcat servlet engine tomcat9 [OK]").

140

141

142

Note that your wiki is absolutely empty, like a WAR installation. Distribution Wizard will take care of the rest.

143

144

145

== Using PostgreSQL ==

146

147

It's as simple as the MySQL installation, you only need to choose the right virtual package.

148

149

150

sudo apt-get install xwiki-tomcat9-pgsql

151

152

153

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##

154

155

PostgreSQL is slightly different than MySQL in the handling of databases and in the manual configuration, but everything should work on the first try.

156

157

== Security settings ==

158

159

1. (((

160

Open ##/etc/xwiki/xwiki.cfg## file and change lines:

...

#-# Cookie encryption keys. You SHOULD replace these values with any random string,

165

#-# as long as the length is the same.

166

xwiki.authentication.validationKey=your1stkeyhere

167

xwiki.authentication.encryptionKey=your2ndkeyhere

...

)))

1. (((

If you need, add password to the built-in superadmin account, by changing line:

...

#-# Enable to allow superadmin. It is disabled by default as this could be a

177

#-# security breach if it were set and you forgot about it. Should only be enabled

178

#-# for recovering the Wiki when the rights are completely messed.

179

xwiki.superadminpassword=yourpassword

...

)))

== Tomcat Usability ==

185

186

You can find [[various generic advices and troubleshooting related to Tomcat>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationTomcat.WebHome]].

=== Java Version ===

Make sure Tomcat is executed with the right [[Java version>>platform:AdminGuide.Installation||anchor="HHardwareandSoftwarerequirements"]].

191

192

This is usually indicated in the file ##/etc/default/tomcat9## (or ##/etc/default/tomcat8## for Tomcat 8, etc).

=== Memory ===

The default Tomcat memory setup is too low for XWiki's needs.

197

198

You can change it in the file ##/etc/default/tomcat9## (or ##/etc/default/tomcat8## for Tomcat 8, etc).

199

200

Modify the property ##JAVA_OPTS##. For example:

201

202

203

JAVA_OPTS="-Djava.awt.headless=true -Xmx1024m"

204

205

206

You should [[check the Memory settings we recommend>>Documentation.AdminGuide.Performances||anchor="HMemory"]].

=== /dev/urandom ===

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:

211

212

* edit ##/etc/default/tomcat9## file and add

213

214

215

JAVA_OPTS="${JAVA_OPTS} -Djava.security.egd=file:/dev/./urandom"

= Concluding Step =

{{include reference="Documentation.AdminGuide.Installation.InstallationConcludingSteps.WebHome"/}}

= Uninstallation =

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:

225

226

227

sudo apt-get --purge remove xwiki-common

228

229

230

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

231

232

233

sudo apt-get --purge autoremove

= Troubleshooting =

You can find a generic Troubleshooting section on [[https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Installation/#HTroubleshooting]].

239

240

== Getting "##The repository 'http:~/~/maven.xwiki.org stable/ Release' is no longer signed.##" ==

241

242

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:

243

244

245

wget -q "https://maven.xwiki.org/public.gpg" -O- | sudo apt-key add -

246

247

248

== My wiki is empty after upgrading a Tomcat9 based package ==

249

250

=== Upgrading from another Tomcat 9 based package ===

251

252

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).

253

254

You will need to find where was the data stored and move it to ##/var/lib/xwiki/data##.

255

256

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".

257

258

=== Previous from a package based on a version of Tomcat lower than 9 ===

259

260

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.

261

262

The workaround is to execute the following commands:

263

264

* {{code language="sh"}}mkdir /etc/systemd/system/tomcat9.service.d/{{/code}}

265

* {{code language="sh"}}echo -e "[Service]\nReadWritePaths=/var/lib/xwiki/data" > /etc/systemd/system/tomcat9.service.d/override.conf{{/code}}

266

* {{code language="sh"}}systemctl daemon-reload{{/code}}

267

* {{code language="sh"}}systemctl restart tomcat9.service{{/code}}

== Java ==

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:

272

273

> Failed to execute the [chart] macro. Cause: [Could not initialize class org.jfree.chart.JFreeChart].

274

275

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.

276

277

To disable it go to ##/etc/java-8-openjdk/accessibility.properties## (or another path depending on your version of Java) and comment the line:

278

279

280

# assistive_technologies=org.GNOME.Accessibility.AtkWrapper

== Tomcat ==

See [[Tomcat Installation>>platform:AdminGuide.InstallationTomcat||anchor="HTroubleshooting"]] for generic Tomcat related issues.

== MySQL ==

See [[MySQL Installation>>platform:AdminGuide.InstallationMySQL||anchor="HTroubleshooting"]] for generic MySQL related issues.

== PostgreSQL ==

See [[PostgreSQL Installation>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationPostgreSQL||anchor="HTroubleshooting"]] for generic PostgreSQL related issues.

294

295

= Other useful info =

296

297

== XWiki as root webapp (short URLs) ==

298

299

300

When doing it make sure to check after upgrade if all is OK in /etc/tomcat9/Catalina/localhost folder (xwiki.xml might be restored).

301

302

303

* Rename file ##/etc/tomcat9/Catalina/localhost/xwiki.xml## into ##/etc/tomcat9/Catalina/localhost/ROOT.xml##

304

* Edit file ##/etc/xwiki/xwiki-tomcat9.xml## and modify ##Context## XML element path from ##/xwiki## to ##/## as in moving from(((

305

306

<Context path="/xwiki" docBase="/usr/lib/xwiki"

307

containerSciFilter="org.apache.tomcat.websocket.server.WsSci|org.apache.jasper.servlet.JasperInitializer">

to

<Context path="/" docBase="/usr/lib/xwiki"

314

containerSciFilter="org.apache.tomcat.websocket.server.WsSci|org.apache.jasper.servlet.JasperInitializer">

315

316

)))

317

* Edit file ##/etc/xwiki/xwiki.cfg## and uncomment {{code language="properties"}}xwiki.webapppath={{/code}}

318

319

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]].

320

321

== Integrate with LibreOffice ==

322

323

Install libreoffice with {{code language="none"}}sudo apt-get install libreoffice{{/code}}.

324

325

And setup XWiki to automatically start and access libreoffice in ##/etc/xwiki/xwiki.properties##:

326

327

328

openoffice.autoStart=true

329

openoffice.homePath=/usr/lib/libreoffice/

330

331

332

See [[Office Importer Application>>extensions:Extension.Office Importer Application]] for more details.

333

334

== Standalone Solr setup ==

335

336

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.

337

338

Then you will need to add the XWiki schema configuration:

339

340

* since 12.6 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)

341

* between 12.0 and 12.5 the package ##xwiki-solr-core## will automatically register the XWiki search core in the Solr server (provided the standard setup was used)

342

* before 12.0 you can use the xwiki-solr-data Debian package and add some links to register it in your Solr server

343

344

= Overview of the important files =

345

346

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.

== XWiki ==

The configuration: **/etc/xwiki/**

351

352

* hibernate.cfg.xml //Hibernate configuration, helping to configure the database resources//

353

* xwiki.cfg

354

* xwiki.properties

355

* xwiki-tomcat9-systemd.conf // Injected trough ##/etc/systemd/system/tomcat9.service.d/xwiki-tomcat-systemd.conf##// in the tomcat9 service configuration

356

* xwiki-tomcat<version> // The Tomcat integration linked from ##/etc/tomcat<version>/Catalina/localhost##//

357

358

The permanent directory: **/var/lib/xwiki/data**

359

360

The home directory: **/usr/lib/xwiki/**

361

362

* META-INF

363