Installation using Debian/Ubuntu (.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

10

Before XWiki 17, a critical dependency of the XWiki Tomcat Debian packages was **tomcat9**. Unfortunately Debian decided to remove the ##tomcat9## package to keep only ##tomcat10## starting with Debian 12 (bookworm) and Ubuntu 24.04. The current alternatives are:

11

12

* use the xjetty based packages instead

13

* upgrade to XWiki 17+

14

* use an [[alternative non Debian specific install method>>xwiki:Documentation.AdminGuide.Installation||anchor="HInstallationMethods"]].

15

16

17

== APT Configuration ==

18

19

First, you have to configure your package manager in order to use XWiki's repository. This can be done simply, using this command:

20

21

22

sudo wget https://maven.xwiki.org/xwiki-keyring.gpg -O /usr/share/keyrings/xwiki-keyring.gpg

23

sudo wget "https://maven.xwiki.org/stable/xwiki-stable.list" -O /etc/apt/sources.list.d/xwiki-stable.list

Note that there are several repositories you can choose (as alternatives to the stable one you have in the previous example):

28

29

* [[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)

30

* [[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)

31

* [[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]]

32

33

34

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

sudo apt-get update

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

41

42

43

apt-cache search xwiki

44

45

46

* Common packages not tied to any application server or database

47

** ##xwiki-common## - XWiki, you can install this if you want to take care yourself of the database and application server

48

** ##xwiki-mariadb-common## - XWiki MariaDB common package, you can install this if you want to take care yourself of the application server

49

** ##xwiki-mysql-common## - XWiki MySQL common package, you can install this if you want to take care yourself of the application server

50

** ##xwiki-pgsql-common## - XWiki PostgreSQL common package, you can install this if you want to take care yourself of the application server

51

52

* Packages based on a customized Jetty packaged for XWiki

53

** ##xwiki-xjetty-common## - XWiki Jetty common package, you can install this if you want to take care yourself of the database link

54

** ##xwiki-xjetty-mariadb## - XWiki Jetty/MariaDB based package

55

** ##xwiki-xjetty-mysql## - XWiki Jetty/MySQL based package

56

** ##xwiki-xjetty-pgsql## - XWiki Jetty/PostgreSQL

57

58

* Packages based on the standard Tomcat package

59

** ##xwiki-tomcat9-common## - XWiki Tomcat 9 common package, you can install this if you want to take care yourself of the database link

60

** ##xwiki-tomcat10-common## - XWiki Tomcat 10 common package, you can install this if you want to take care yourself of the database link

61

** ##xwiki-tomcat9-mariadb## - XWiki Tomcat 9/MariaDB based package

62

** ##xwiki-tomcat10-mariadb## - XWiki Tomcat 10/MariaDB based package

63

** ##xwiki-tomcat9-mysql## - XWiki Tomcat 9/MySQL based package

64

** ##xwiki-tomcat10-mysql## - XWiki Tomcat 10/MySQL based package

65

** ##xwiki-tomcat9-pgsql## - XWiki Tomcat 9/PostgreSQL

66

** ##xwiki-tomcat10-pgsql## - XWiki Tomcat 10/PostgreSQL

67

68

* Not really XWiki itself but Solr cores needed when you want to use a standalone Solr instance with XWiki

69

** ##xwiki-solr9-all## - An entry point package with dependencies on all the Solr 9 cores required to setup a standalone version compatible with XWiki Standard

70

** ##xwiki-solr9-search## - A pre configured Solr 9 core for the XWiki search feature

71

** ##xwiki-solr9-events## - A pre configured Solr 9 core for the XWiki events/notifications storage

72

** ##xwiki-solr9-ratings## - A pre configured Solr 9 core for the XWiki rating storage

73

** ##xwiki-solr9-extension_index## - A pre configured Solr 9 core for the XWiki extensions index

74

75

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

76

77

78

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.

83

84

85

== Complete Installation ==

86

87

88

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.

89

90

91

=== Using MariaDB ===

92

93

94

Note that XWiki requires at least MariaDB 10.2.

Xjetty:

sudo apt install xwiki-xjetty-mariadb

Tomcat 10:

sudo apt install xwiki-tomcat10-mariadb

Tomcat 9:

sudo apt install xwiki-tomcat9-mariadb

113

114

115

During the installation you may get some questions from DBconfig, which is in charge of the configuration of XWiki with the MariaDB database. Don't confuse it with the MariaDB root password prompt that asks you for a root password (which is intented for the superuser). If you haven't already installed any MariaDB databases and you are not familiar with it you should let DBconfig handle this.

116

117

Afterwards DBconfig asks you for the MariaDB root password for the "xwiki" MariaDB user. This user will be used to connect to MariaDB from the XWiki application. You should choose the password wisely but you don't have to pay a lot of attention to it after that because DBconfig internally configures XWiki to start up with these credentials.

118

119

120

The password should not contain any special characters, otherwise XWiki will fail to start. See [[https:~~/~~/jira.xwiki.org/browse/XWIKI-14406>>https://jira.xwiki.org/browse/XWIKI-14406]]

121

122

123

The installation ends with the start of the XWiki or Tomcat daemon which is also setup to start automatically from boot.

=== Using MySQL ===

Note that XWiki requires at least MySQL 5.7. It's not recommended to use this package if your "MySQL" server is in fact MariaDB, see [[the MariaDB section>>||anchor="#HUsingMariaDB"]].

Xjetty:

sudo apt install xwiki-xjetty-mysql

Tomcat 10:

sudo apt install xwiki-tomcat10-mysql

Tomcat 9:

sudo apt install xwiki-tomcat9-mysql

147

148

149

Everything else is similar to what is described in the [[the MariaDB section>>||anchor="#HUsingMariaDB"]].

150

151

=== Using PostgreSQL ===

152

153

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

Xjetty:

sudo apt install xwiki-xjetty-pgsql

Tomcat 10:

sudo apt install xwiki-tomcat10-pgsql

Tomcat 9:

sudo apt install xwiki-tomcat9-pgsql

171

172

173

Everything else is similar to what is described in the [[the MariaDB section>>||anchor="#HUsingMariaDB"]].

174

175

=== Starting up XWiki for the first time... ===

176

177

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>>http://localhost:8080/xwiki]]##

178

179

180

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

== Performance ==

=== XWiki ===

You can find various [[various generic advices and troubleshooting related to XWiki>>Documentation.AdminGuide.Performances]].

=== Tomcat ===

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

192

193

==== Java Version ====

194

195

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

196

197

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.

202

203

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

204

205

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

206

207

208

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

209

210

211

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

212

213

==== /dev/urandom ====

214

215

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:

216

217

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

218

219

220

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

221

222

223

== Concluding Step ==

224

225

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

== Upgrading ==

=== Update the packages index

sudo apt update

=== Upgrade the packages

sudo apt upgrade

This will upgrade all packages, not just XWiki. If you want to avoid all the other packages and only update XWiki, you can use {{code}}sudo apt install xwiki-tomcat9-mariadb{{/code}} (change ##xwiki-tomcat9-mariadb## for the top level package you installed if you installed something else).

242

243

244

Sometimes (especially in case of new cycle), apt upgrade might report that it refuse to upgrade some xwiki packages.

245

246

This is generally the sign that either:

247

* A new dependency cannot be found: it generally means that XWiki starts requiring a more recent version of Java and the Debian repository you have don't have any implementation of this Java versions. See [[No package can be found for Java>>Documentation.AdminGuide.Installation.InstallationViaAPT||anchor="HNopackagecanbefoundforJava"]] for more details on how to resolve this situation.

248

* Some xwiki package name changed: this generally happen when XWiki stops supporting some version of Tomcat and you need to install a different ##xwiki-tomcat*## package (for example XWiki 17 does not support tomcat9 anymore and requires the ##tomcat10## package so xwiki packages for this version have been renamed to ##xwiki-tomcat10-mariadb## for example, if you used ##mariadb##).

249

250

251

=== Upgrade the pages

252

253

Like in the case of the install, you still have to go through the Distribution Wizard. See more details on [[Upgrading the flavor>>Documentation.AdminGuide.Upgrade||anchor="HPart2Upgradingtheflavor"]].

== Uninstallation ==

If you want to remove XWiki from your system, you only have to uninstall the packages you've installed at the beginning of this documentation. For example:

258

259

260

sudo apt-get --purge remove xwiki-common

261

262

263

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

264

265

266

sudo apt-get --purge autoremove

267

268

269

== Troubleshooting ==

270

271

=== Log file location ===

272

273

This installation manual should guide you all the way to a fresh and clean XWiki platform. If on the other hand issues may arise, it is important to inspect the XWiki log file for any WARNING messages that may have been brought up. Below you can find the location of this log file for the respective application servers.

==== XJetty ====

/var/log/xwiki/[date].jetty.log

==== Tomcat9 ====

There are several possibilities depending on the distribution:

284

285

286

/var/log/tomcat9/catalina.out

287

/var/log/tomcat9/Catalina.[date].log

288

289

290

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

291

292

=== No package can be found for Java ===

293

294

XWiki require at least Java 8 since XWiki 8.1 and Java 11 since XWiki 14.0, **OpenJDK 17** (the recommended version) will be automatically installed as dependency on recent distributions.

295

296

If your Debian based distribution does not provide any package for the Java version you need you can try with:

297

298

* Adoptium provides a Debian repository to install Temurin (OpenJDK), see https://adoptium.net/installation/linux/#_deb_installation_on_debian_or_ubuntu

=== Tomcat ===

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

=== MySQL ===

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

=== PostgreSQL ===

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

311

312

== Other useful info ==

313

314

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

315

316

Note that this section is only the part of Short URL specific to the Debian setup. To fully configure the URL to your liking, see [[full documentation on short URLs>>doc:Documentation.AdminGuide.ShortURLs.WebHome]].

317

318

==== For Tomcat 9 ====

319

320

321

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

322

323

324

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

325

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

326

327

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

328

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

to

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

335

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

336

337

)))

338

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

* Restart Tomcat 9.

==== For Jetty ====

You have to modify the ##xjetty-web.xml## file

345

346

The WebAppContext from the xwiki-jetty configuration has to be modified so that Jetty actually serves the XWiki application from the root-path. For this you have to modify the ##/etc/xwiki/xjetty-web.xml## and add the following directive.

=== Integrate with LibreOffice ===

354

355

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

356

357

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

358

359

360

openoffice.autoStart=true

361

openoffice.homePath=/usr/lib/libreoffice/

362

363

364

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

365

366

=== Standalone Solr setup ===

367

368

Take a look at [[Solr documentation>>https://solr.apache.org/guide/solr/latest/deployment-guide/taking-solr-to-production.html]] to install Solr itself.

369

370

Then you will need to add the XWiki schema configuration: you should install the package ##xwiki-solr-all## for Solr 8 or {{version since="XWiki 16.2.0"}}##xwiki-solr9-all## for Solr 9{{/version}} to automatically register the Solr cores needed by XWiki Standard in the Solr server (provided the standard Solr setup was used).

371

372

=== Access a file from XWiki ===

373

374

SystemD is configured to prevent XWiki from accessing an arbitrary file on the file system, even if the system user which runs XWiki would normally be allowed to access it. You can control this in the file ##/etc/systemd/system/tomcat9.service.d/xwiki-tomcat9-systemd.conf## when using ##xwiki-tomcat9-common## and ##/lib/systemd/system/xwiki.service## when using ##xwiki-xjetty-common## and by the default XWiki is allowed and write ##/var/lib/xwiki/data##. Note that once you modified one of those files, you will need to execute ##sudo systemctl daemon-reload## and restart the service.

375

376

== Overview of the important files ==

377

378

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/**

383

384

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

385

* xwiki.cfg

386

* xwiki.properties

387

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

388

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

389

390

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

391

392

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

* META-INF

* resources

* skins

* templates

* WEB-INF

** hibernate.cfg.xml -> /etc/xwiki/hibernate.cfg.xml

400

** xwiki.cfg -> /etc/xwiki/xwiki.cfg

401

** xwiki.properties -> /etc/xwiki/xwiki.properties

=== XJetty ===

**/lib/systemd/system/xwiki.service** is the configuration in charge of controlling the ##xwiki## service, it's also where you can customize its java startup configuration

=== Tomcat ===

**/etc/tomcat##<version>##/**

* context.xml

* logging.properties