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

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]]: all released Cycle LTS versions.

32

* [[https:~~/~~/maven.xwiki.org/lts/xwiki-lts-latest.list>>https://maven.xwiki.org/recommended/xwiki-lts-latest.list]]: latest LTS versions (can be the Cycle LTS or the Intermediate LTS versions if they higher).

33

34

Check out the the [[Support page>>xwiki:Main.Support]] for more information on the various branches we support.

35

36

37

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.

44

45

46

apt-cache search xwiki

47

48

49

* Common packages not tied to any application server or database

50

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

51

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

52

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

53

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

54

55

* Packages based on a customized Jetty packaged for XWiki

56

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

57

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

58

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

59

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

60

61

* Packages based on the standard Tomcat package

62

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

63

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

64

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

65

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

66

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

67

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

68

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

69

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

70

71

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

72

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

73

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

74

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

75

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

76

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

77

78

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

79

80

81

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.

86

87

88

== Complete Installation ==

89

90

91

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.

92

93

94

=== Using MariaDB ===

95

96

97

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

116

117

118

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.

119

120

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.

121

122

123

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

124

125

126

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

150

151

152

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

153

154

=== Using PostgreSQL ===

155

156

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

174

175

176

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

177

178

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

179

180

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

181

182

183

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

195

196

==== Java Version ====

197

198

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

199

200

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.

205

206

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

207

208

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

209

210

211

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

212

213

214

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

215

216

== Concluding Step ==

217

218

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

== Upgrading ==

=== Update the packages index ===

sudo apt update

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

229

230

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.

231

232

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

233

234

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

235

236

237

sudo systemctl stop tomcat9

238

239

240

* Uninstall Tomcat (which will also uninstall the xwiki packages which rely on this version of Tomcat):

241

242

243

sudo apt remove tomcat9

244

245

246

* Then you will need to install the new package ({{warning}}modify the package name to match the version of Tomcat you are upgrading to, and the database you were already using{{/warning}}):

247

248

249

sudo apt install xwiki-tomcat10-mariadb

250

251

252

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

259

260

261

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

262

263

This is generally the sign that either:

264

265

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

266

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

267

268

269

=== Upgrade the pages ===

270

271

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:

276

277

278

sudo apt-get --purge remove xwiki-common

279

280

281

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

282

283

284

sudo apt-get --purge autoremove

285

286

287

== Troubleshooting ==

288

289

=== Log file location ===

290

291

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:

302

303

304

/var/log/tomcat10/catalina.out

305

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

306

/var/log/tomcat9/catalina.out

307

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

308

309

310

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

311

312

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

313

314

XWiki require at least Java 17 since XWiki 16.0.

315

316

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

317

318

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

331

332

== Other useful info ==

333

334

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

335

336

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

337

338

==== For Tomcat 9 ====

339

340

341

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

342

343

344

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

345

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

346

347

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

348

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

to

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

355

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

356

357

)))

358

* 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

365

366

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.

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

374

375

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/jetty-web.xml## and add the following directive.

=== Integrate with LibreOffice ===

383

384

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

385

386

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

387

388

389

openoffice.autoStart=true

390

openoffice.homePath=/usr/lib/libreoffice/

391

392

393

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

394

395

=== Standalone Solr setup ===

396

397

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

398

399

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

400

401

=== Access a file from XWiki ===

402

403

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.

404

405

== Overview of the important files ==

406

407

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

412

413

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

414

* xwiki.cfg

415

* xwiki.properties

416

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

417

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

418

419

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

420

421

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

* META-INF

* resources

* skins

* templates

* WEB-INF

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

429

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

430

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