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

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

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

15

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

20

21

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

22

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

23

* [[https:~~/~~/maven.xwiki.org/lts/xwiki-lts.list>>https://maven.xwiki.org/lts/xwiki-lts.list]]: all released Cycle LTS versions.

24

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

25

26

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

27

28

29

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

sudo apt update

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

apt search xwiki

* Common package not tied to any application server or database

42

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

43

44

* Common packages not tied to any 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

49

* Packages based on a customized Jetty packaged for XWiki

50

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

51

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

52

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

53

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

54

55

* Packages based on the standard Tomcat package (they do not include Tomcat, they depend on it so the pacjage you use generally depends on what version of Tomcat is available on your distribution's repositories)

56

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

57

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

58

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

59

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

60

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

61

** ##xwiki-tomcat11-mariadb## - XWiki Tomcat 11/MariaDB based package

62

** ##xwiki-tomcat11-mysql## - XWiki Tomcat 11/MySQL based package

63

** ##xwiki-tomcat11-pgsql## - XWiki Tomcat 11/PostgreSQL

64

65

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

66

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

67

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

68

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

69

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

70

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

71

72

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

73

74

75

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.

80

81

82

== Complete Installation ==

83

84

85

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.

86

87

88

=== Using MariaDB ===

89

90

91

Note that XWiki requires at least MariaDB 10.2.

Tomcat:

sudo apt install xwiki-tomcat10-mariadb

Xjetty:

sudo apt install xwiki-xjetty-mariadb

104

105

106

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.

107

108

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.

109

110

111

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

112

113

114

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

Tomcat:

sudo apt install xwiki-tomcat10-mysql

Xjetty:

sudo apt install xwiki-xjetty-mysql

132

133

134

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

135

136

=== Using PostgreSQL ===

137

138

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

Tomcat:

sudo apt install xwiki-tomcat10-pgsql

Xjetty:

sudo apt install xwiki-xjetty-pgsql

150

151

152

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

153

154

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

155

156

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

157

158

159

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.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.WebHome]].

171

172

==== Java Version ====

173

174

Make sure Tomcat is executed with the right [[Java version>>dev:Community.SupportStrategy.JavaSupportStrategy.WebHome]].

175

176

This is usually indicated in the file ##/etc/default/tomcat10## (or ##/etc/default/tomcat11## for Tomcat 11, etc).

==== Memory ====

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

181

182

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

183

184

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

185

186

187

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

188

189

190

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

191

192

== Concluding Step ==

193

194

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

== Upgrading ==

=== Update the packages index ===

sudo apt update

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

205

206

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>>dev:Community.SupportStrategy.ServletContainerSupportStrategy.WebHome]]), 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.

207

208

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.

209

210

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

211

212

213

sudo systemctl stop tomcat9

214

215

216

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

217

218

219

sudo apt remove tomcat9

220

221

222

* 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}}):

223

224

225

sudo apt install xwiki-tomcat10-mariadb

226

227

228

=== 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-tomcat10-mariadb{{/code}} (change ##xwiki-tomcat10-mariadb## for the top level package you installed if you installed something else).

235

236

237

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

238

239

This is generally the sign that either:

240

241

* A new dependency cannot be found: it generally means that [[XWiki starts requiring a more recent version of Java>>dev:Community.SupportStrategy.JavaSupportStrategy||anchor="HByXWikiVersions"]] 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.

242

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

243

244

245

=== Upgrade the pages ===

246

247

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:

252

253

254

sudo apt-get --purge remove xwiki-common

255

256

257

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

258

259

260

sudo apt-get --purge autoremove

261

262

263

== Troubleshooting ==

264

265

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

266

267

XWiki require at least Java 17 since XWiki 16.0 and Java 21 since XWiki 18.0.0.

268

269

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

270

271

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

=== Tomcat ===

See [[Tomcat troubleshootings>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.troubleshooting.WebHome]] 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.

284

285

=== Log file location ===

286

287

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:

298

299

300

/var/log/tomcat10/catalina.out

301

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

302

303

304

You can find a generic Troubleshooting section on [[Troubleshooting>>documentation.xs.admin.installation.troubleshooting.WebHome]].

305

306

== Other useful info ==

307

308

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

309

310

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

311

312

==== For Tomcat 10+ ====

313

314

315

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

316

317

318

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

319

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

320

321

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

322

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

to

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

329

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

330

331

)))

332

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

* Restart Tomcat.

==== For Jetty ====

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

339

340

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 ##xjetty-web.xml## file

348

349

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

357

358

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.

(% data-xwikiorg-product="XWiki" data-xwikiorg-versions-range="3" data-xwikiorg-versions-since="17.0.0" %)You have to modify the ##jetty-web.xml## file

366

367

(% data-xwikiorg-product="XWiki" data-xwikiorg-versions-range="3" data-xwikiorg-versions-since="17.0.0" %)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.

368

369

(% data-xwikiorg-product="XWiki" data-xwikiorg-versions-range="3" data-xwikiorg-versions-since="17.0.0" %){{code language="xml"}}<Set name="contextPath">/</Set>{{/code}}

370

371

{{{<Set name="contextPath">/</Set>}}}

372

373

=== Integrate with LibreOffice ===

374

375

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

376

377

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

378

379

380

openoffice.autoStart=true

381

openoffice.homePath=/usr/lib/libreoffice/

382

383

384

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

385

386

=== Standalone Solr setup ===

387

388

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

389

390

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

391

392

=== Access a file from XWiki ===

393

394

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:

395

396

* ##/etc/systemd/system/tomcat10.service.d/xwiki-tomcat10-systemd.conf## when using a ##xwiki-tomcat10-*## package

397

* ##/lib/systemd/system/xwiki.service## when using a ##xwiki-xjetty-*## package

398

399

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

400

401

== Overview of the important files ==

402

403

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

408

409

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

410

* xwiki.cfg

411

* xwiki.properties

412

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

413

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

414

415

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

416

417

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

* META-INF

* resources

* skins

* templates

* WEB-INF

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

425

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

426

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