How to Install XWiki 9.11.x on Ubuntu 16.04 LTS

Published on: Fri, May 11, 2018 at 11:32 am EST
Linux Guides Server Apps Ubuntu

XWiki is a popular, enterprise-level open source wiki platform written in Java. With extensibility and ease of use, XWiki is being deployed in various companies as a knowledge repository, public portal, and more.

In this article, I will guide you through the process of installing XWiki 9.11.2 on an Ubuntu 16.04 LTS server instance. OpenJDK 8, Tomcat 8 and MySQL 5.7 will be automatically installed as dependencies during the installation process.

Prerequisites

  • A fresh Vultr Ubuntu 16.04 LTS x64 server instance with at least 2GB of memory, 4GB or more recommended. Say its IP address is 203.0.113.1.
  • A sudo user.
  • The server instance has been updated to the latest stable status using apt.

Setup the XWiki LTS APT repo

Log in as a sudo user, and then download and setup the XWiki LTS (Long Term Support) APT repo on your server instance:

cd
wget -q "https://maven.xwiki.org/public.gpg" -O- | sudo apt-key add -
sudo wget "https://maven.xwiki.org/lts/xwiki-lts.list" -P /etc/apt/sources.list.d/
sudo apt update

Note: If you want to try out the latest stable XWiki release (but NOT LTS), you can download the below XWiki APT repo instead:

cd
wget -q "https://maven.xwiki.org/public.gpg" -O- | sudo apt-key add -
sudo wget "https://maven.xwiki.org/stable/xwiki-stable.list" -P /etc/apt/sources.list.d/
sudo apt update

Install the all in one XWiki bundle (including XWiki LTS 9.11.2, Tomcat 8, MySQL 5.7, and more.)

When deployed in production, XWiki needs to work with a Java Servlet container and database software. As a flexible wiki platform, XWiki officially provides various integration options. You can use the following command to show all available options in the XWiki LTS APT repo:

apt search xwiki

The search result will resemble the following:

xwiki-common/lts 9.11.2 all
xwiki-mysql-common/lts 9.11.2 all
xwiki-pgsql-common/lts 9.11.2 all
xwiki-solr-data/lts 9.11.2 all
xwiki-tomcat7-common/lts 9.11.2 all
xwiki-tomcat7-mysql/lts 9.11.2 all
xwiki-tomcat7-pgsql/lts 9.11.2 all
xwiki-tomcat8-common/lts 9.11.2 all
xwiki-tomcat8-mysql/lts 9.11.2 all
xwiki-tomcat8-pgsql/lts 9.11.2 all

If you want to use XWiki with the most common dependencies, you can install all required components in one command as follows:

sudo apt install xwiki-tomcat8-mysql/lts -y

During the installation process, you will be asked to setup a new password for the MySQL root user several times. Just leave the password field blank and press Enter to skip this step for now. We will tackle this problem later while securing the installation of MySQL.

When being asked whether you want to Configure database for xwiki with dbconfig-common?, choose <Yes> and then press ENTER.

When being asked to provide a MySQL application password for xwiki, you can either input a specific MySQL application password or leave the password field blank. The latter will tell XWiki to use a random MySQL application password.

Having XWiki and all of the required dependencies installed, secure the installation of MySQL:

sudo /usr/bin/mysql_secure_installation

During the process, the program will ask you a few questions. Reply to them as below:

  • Would you like to setup VALIDATE PASSWORD plugin? Y
  • Please enter 0 = LOW, 1 = MEDIUM and 2 = STRONG: 2
  • New password: a-strong-MySQL-root-password
  • Re-enter new password: a-strong-MySQL-root-password
  • Do you wish to continue with the password provided? Y
  • Remove anonymous users? Y
  • Disallow root login remotely? Y
  • Remove test database and access to it? Y
  • Reload privilege tables now? Y

Enhance the security of XWiki by modifying the XWiki config file.

Use the vi editor to open an XWiki config file:

sudo vi /etc/xwiki/xwiki.cfg

Find the two lines shown below:

xwiki.authentication.validationKey=totototototototototototototototo
xwiki.authentication.encryptionKey=titititititititititititititititi

Replace both parameters' values with two different random strings, and just make sure that the length of each string is the same as the other one, for example:

xwiki.authentication.validationKey=f0130dfa6fc841e920d5e1056184c03e
xwiki.authentication.encryptionKey=z84kf92ko073tgjdnvkdfmms91qa0ke4

Save and quit:

:wq!

The default memory quota is too low for running Tomcat 8 and XWiki within. You need to increase the default memory quota as follows before you can start an XWiki instance in Tomcat 8 properly.

sudo cp /etc/default/tomcat8 /etc/default/tomcat8.bak
sudo vi /etc/default/tomcat8

Find the line:

JAVA_OPTS="-Djava.awt.headless=true -Xmx128m -XX:+UseConcMarkSweepGC"

Modify the the line as shown below:

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

Note: 1024M of memory is only the minimum quota for running a small or medium XWiki site. You may need to make adjustments to this line in accordance with your specific demands.

Save and quit:

:wq!

Restart Tomcat 8 in order to bring all of your modifications into effect:

sudo systemctl restart tomcat8.service

Modify UFW firewall rules in order to allow web access on port 8080:

sudo ufw allow 8080
sudo ufw enable

Initialize XWiki on the "Distribution Wizard" web interface

At this point, you have setup a functional but empty XWiki site. In order to fill in content, you need to finish several follow-up tasks, including creating an admin user and installing a flavor and required extensions for this wiki, on the initial XWiki web interface named "Distribution Wizard".

Point your favorite web browser to http://203.0.113.1:8080/xwiki, and you will be automatically brought onto the "Distribution Wizard" web interface. Click the "Continue" button to begin the wizard.

On the "Step 1 - Admin user" page, you need to input the admin user's credentials, for example:

FIRST NAME: `John`
LAST NAME: `Doe`
USERNAME (Required): `johndoe`
PASSWORD (Required): `yourpassword`
CONFIRM PASSWORD (Required): `yourpassword`
EMAIL ADDRESS: `johndoe@example.com`

Having filled out all of the required fields, Click the "Register and login" button to move on.

On the next page which shows "You are connected with user John Doe.", click the "Continue" button to create the admin user John Doe whose username is johndoe and move on.

On the "Step 2 - Flavor" page, click on the "XWiki Standard Flavor 9.11.2" area to highlight this flavor, and then click the "Install this flavor" button to move on.

On the next page which details the "XWiki Standard Flavor 9.11.2", click the "Install" button to perform the installation.

Having the flavor installed, all of the required extensions will be listed on the page, click the "Continue" button to install them all.

Having the flavor and all of the required extensions installed, click the "Continue" button at the bottom right corner to move on.

On the "Step 4 - Report" page, you can review all of the pages created.

If necessary, you can delete any unpopular pages by clicking the corresponding red X button.

Finally, click the "Continue" button to finish the "Distribution Wizard". You will be brought into the XWiki dashboard as the admin user you had setup earlier.

(Optional) Shorten the XWiki site URL

By default, since Tomcat can serve more than one application at the same time, you need to access your XWiki site at the URL http://203.0.113.1:8080/xwiki. However, if XWiki is the only application running in Tomcat and you want to shorten the XWiki site's URL by removing the /xwiki suffix, you should modify three XWiki config files as follows.

File modification 1:

cd /etc/tomcat8/Catalina/localhost/
sudo cp xwiki.xml ROOT.xml
sudo mv xwiki.xml xwiki.xml.bak

File modification 2:

cd /etc/xwiki
sudo cp xwiki-tomcat8.xml xwiki-tomcat8.xml.bak
sudo vi xwiki-tomcat8.xml

Find the line:

<Context path="/xwiki" docBase="/usr/lib/xwiki" privileged="true" crossContext="true">

Modify the value of the path parameter:

<Context path="/" docBase="/usr/lib/xwiki" privileged="true" crossContext="true">

Save and quit:

:wq!

File modification 3:

cd /etc/xwiki
sudo cp xwiki.cfg xwiki.cfg.bak
sudo vi xwiki.cfg

Find the line:

# xwiki.webapppath=

Uncomment it:

xwiki.webapppath=

Save and quit:

:wq!

Finally, restart Tomcat 8 in order to apply all of your modifications:

sudo systemctl restart tomcat8.service

From now on, you will visit your XWiki site from http://203.0.113.1:8080/ directly.

(Optional) Setup an Nginx reverse proxy

By default, Tomcat 8 works on port 8080, and you can only visit your XWiki site from the same port. If you want to facilitate visitors' access by removing the port number part, you can install Nginx as a reverse proxy between XWiki and visitors.

First, install Nginx using apt:

sudo apt install nginx -y

Next, setup Nginx as a reverse proxy by modifying its default site configurations:

cd /etc/nginx/sites-available
sudo mv default default.bak
sudo vi default

Fill in the file with the following:

server {
listen 0.0.0.0:80;

proxy_request_buffering off;
proxy_buffering off;

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_redirect     off;
        proxy_set_header   Host $host;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Host $server_name;
}
}

Save and quit:

:wq!

Start the Nginx service and set it to automatically start on system startup:

sudo systemctl restart nginx.service
sudo systemctl enable nginx.service

Finally, modify the UFW firewall rules accordingly:

sudo ufw allow 80
sudo ufw deny 8080
sudo ufw reload

From now on, visitors to your XWiki site no longer need to specify the port number. They should directly visit http://203.0.113.1/.

Want to contribute ?

You could earn up to $300 by adding new articles