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 Memory section>>||anchor="HMemory"]] 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/tomcat10## (or ##/etc/default/tomcat9## for Tomcat 9, 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/tomcat10## (or ##/etc/default/tomcat9## for Tomcat 10, 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

== Concluding Step ==

214

215

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

== Upgrading ==

=== Update the packages index ===

sudo apt update

=== [Optional] Uninstall conflicting version of tomcat packages

226

227

In the case of the ##tomcat## based packages, if you are moving from one version of Tomcat to another (which is generally needed when XWiki increase its [[minimum supported version>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationTomcat||anchor=HInstallationSteps]]), you may need to first uninstall the previous version. This is because two different versions of Tomcat cannot run at the same time by default.

228

229

Of course, you can skip this step if you are not changing the version of Tomcat, or if you configured Tomcat specifically to allow having several versions running at the same time.

230

231

* Stop the running instance of tomcat (change the version to match the previous version of Tomcat you are upgrading from):

232

233

234

sudo systemctl stop tomcat9

* Uninstall Tomcat:

sudo apt remove tomcat9

241

242

243

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

250

251

252

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

253

254

This is generally the sign that either:

255

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

256

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

257

258

259

=== Upgrade the pages ===

260

261

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:

266

267

268

sudo apt-get --purge remove xwiki-common

269

270

271

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

272

273

274

sudo apt-get --purge autoremove

275

276

277

== Troubleshooting ==

278

279

=== Log file location ===

280

281

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

==== Tomcat ====

There are several possibilities depending on the distribution and Tomcat version:

292

293

294

/var/log/tomcat10/catalina.out

295

/var/log/tomcat10/catalina.[date].log

296

/var/log/tomcat9/catalina.out

297

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

298

299

300

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

301

302

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

303

304

XWiki require at least Java 17 since XWiki 16.0.

305

306

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

307

308

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

321

322

== Other useful info ==

323

324

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

325

326

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

327

328

==== For Tomcat 9 ====

329

330

331

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

332

333

334

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

335

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

336

337

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

338

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

to

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

345

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

346

347

)))

348

* 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

355

356

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

364

365

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

366

367

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

368

369

370

openoffice.autoStart=true

371

openoffice.homePath=/usr/lib/libreoffice/

372

373

374

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

375

376

=== Standalone Solr setup ===

377

378

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

379

380

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

381

382

=== Access a file from XWiki ===

383

384

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.

385

386

== Overview of the important files ==

387

388

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

393

394

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

395

* xwiki.cfg

396

* xwiki.properties

397

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

398

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

399

400

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

401

402

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

* META-INF

* resources

* skins

* templates

* WEB-INF

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

410

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

411

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