XWiki on Ubuntu 16.04 LTS with Nginx Reverse Proxy

Install XWiki and all dependant programs on a 4 GB cloud server. This means:

1) Java
2) Tomcat
3) MySQL/MariaDB
4) XWiki
5) Nginx

Here we use Nginx as a reverse proxy to firstly redirect all HTTP to HTTPS and then forward all requests on port 80/443 to port 8080 (tomcat) on the localhost. Here I use LetsEncrytp for my SSL certificates.

Before we begin…

Setup DNS

wiki.dummydomains.org.uk ——>

Prepare the Server


Update and reboot the server.

apt-get update
apt-get dist-upgrade

Enable the firewall

ufw status
ufw enable
ufw allow ssh
ufw reload
ufw status

Install Oracle Java

This is a requirement before installing Tomcat or XWiki. At the time of writing, Java 8.x is recommended as 9.x is too new and has a number of known bugs still.

apt-get install software-properties-common
add-apt-repository ppa:webupd8team/java
apt-get update
apt-get install oracle-java8-installer

You will need to accept the license agreement:

Accept license agreement

Binary code license terms

Because many programs check for $JAVA_HOME, it is a good idea to set it now. If you don’t know the path, check with:

root@wiki:~# update-alternatives --config java
There is 1 choice for the alternative java (providing /usr/bin/java).

  Selection    Path                                     Priority   Status
  0            /usr/lib/jvm/java-8-oracle/jre/bin/java   1081      auto mode
* 1            /usr/lib/jvm/java-8-oracle/jre/bin/java   1081      manual mode

Press <enter> to keep the current choice[*], or type selection number:

Then edit your system $PATH variable so that the /usr/lib/jvm/java-8-oracle is the first path.

nano /etc/environment

Mine looks like this:

root@wiki:~# cat /etc/environment

You will need to log out and back in first but you can test with the below command.

root@wiki:~# echo $JAVA_HOME

Create Virtual Host and Generate SSL

Install Nginx and LetsEncrypt.


Install and configure Nginx.

apt-get install apache2-utils nginx
systemctl enable nginx

Create a very basic virtual host by editing the nginx configuration file and inserting your server name in the server_name variable.

vim /etc/nginx/sites-enabled/default

Mine looks like this.

root@wiki:~# egrep -v "^$|^[[:space:]]*#" /etc/nginx/sites-available/default 
server {
	listen 80 default_server;
	listen [::]:80 default_server;
	root /var/www/html;
	index index.html index.htm index.nginx-debian.html;
	server_name wiki.dummydomains.org.uk;
	location / {
		try_files $uri $uri/ =404;


systemctl restart nginx

Check it works!

Nginx test page
If it doesn’t, check the firewall…

Allow HTTP and HTTPS Traffic

If you use a local firewall like UFW or iptables, you will need to allow port 80 and 443.

ufw status
ufw allow http
ufw allow https
ufw status
ufw reload


add-apt-repository ppa:certbot/certbot
apt-get update
apt-get install python-certbot-nginx
certbot --nginx -d wiki.dummydomains.org.uk -d dummydomains.org.uk

Your certificate will get saved to /etc/letsencrypt/live/wiki.dummydomains.org.uk.

LetsEncrypt will edit your virtual hosts file.  The parts we are interested in are:

  listen 443 ssl; # managed by Certbot
  ssl_certificate /etc/letsencrypt/live/wiki.dummydomains.org.uk/fullchain.pem; # managed by Certbot
  ssl_certificate_key /etc/letsencrypt/live/wiki.dummydomains.org.uk/privkey.pem; # managed by Certbot
  include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
  ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

  if ($scheme != "https") {
    return 301 https://$host$request_uri;
  } # managed by Certbot


Install XWiki

Install XWiki.

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

Search for XWiki packages to install.

apt-cache search xwiki

According to the official documentation, the enterprise version is out-of-date and the non-enterprise version should be used.

apt-get install xwiki-tomcat8-mysql

Set the root MySQL password:


Set root MySQL password
Set root MySQL password

When asked if you should configure the database with dbconfig-common, say yes.

Configure with dbconfig-common
Configure with dbconfig-common

MySQL application password:


Select application password
Select application password

Check tomcat8 is listening on port 8080:

root@wiki:~# netstat -plnt | grep :8080
tcp6       0      0 :::8080                 :::*                    LISTEN      15840/java

Check your memory usage:

root@wiki:~# free -h
              total        used        free      shared  buff/cache   available
Mem:           3.9G        487M        1.9G         10M        1.5G        3.3G
Swap:            0B          0B          0B

You will need to increase the default about of memory allocated to Java. Here’s how:

vim /etc/default/tomcat8


root@wiki:~# grep ^JAVA_OPTS /etc/default/tomcat8
JAVA_OPTS="-Djava.awt.headless=true -Xmx128m -XX:+UseConcMarkSweepGC"


root@wiki:~# grep ^JAVA_OPTS /etc/default/tomcat8
JAVA_OPTS="-Djava.awt.headless=true -Xmx1024m -XX:+UseConcMarkSweepGC"

Restart Tomcat

systemctl restart tomcat8

Test using using a browser:


If you’ve enabled a firewall and you want to test:

ufw allow 8080/tcp
ufw reload

However I’m not going to do this – I’m going to setup Nginx as a proxy first.

Configure Nginx

Remove the default virtual host configuration.

rm -v /etc/nginx/sites-enabled/default.conf
vim /etc/nginx/sites-available/wiki.dummydomains.org.uk.conf

My site configuration look as follows:

upstream tomcat {
  server fail_timeout=0;
  keepalive 64;

server {
  listen [::]:80;
  listen ssl;
  listen [::]:443 ssl;
  server_name wiki.dummydomains.org.uk dummydomains.org.uk;
  ssl_certificate /etc/letsencrypt/live/wiki.dummydomains.org.uk/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/wiki.dummydomains.org.uk/privkey.pem;
  include /etc/letsencrypt/options-ssl-nginx.conf;
  ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
  # redirect http to https
  if ($scheme != "https") {
    return 301 https://$host$request_uri;

  auth_basic "Authentication Required";
  auth_basic_user_file xwiki-access;

  location / {
    client_max_body_size 20M;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Server $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_pass_request_headers on;
    proxy_set_header Connection "keep-alive";
    proxy_store off;
    proxy_headers_hash_max_size 512;
    deny all;

    proxy_pass http://tomcat/;

I also want to password protect my wiki:

htpasswd -c /etc/nginx/xwiki-access andy

Enable the site:

cd /etc/nginx/sites-enabled/
ln -s ../sites-available/xwiki.dummydomains.org.uk.conf .

….and check configuration file for errors.

root@wiki:~# nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Check config and restart Nginx:

systemctl restart nginx

Now try entering the following into your browser and complete the on-screen installation instructions:


Complete Installation

Here are few things I normally do after an installation.

Make Root Application

I want to make this Wiki instance the root web application and remove the trailing /xwiki from the URL.

systemctl stop tomcat8.service
mv -v /etc/tomcat8/Catalina/localhost/xwiki.xml /etc/tomcat8/Catalina/localhost/ROOT.xml
vim /etc/xwiki/xwiki-tomcat8.xml


<Context path="/xwiki" docBase="/usr/lib/xwiki" privileged="true" crossContext="true">
  <!-- make symlinks work in Tomcat -->
  <Resources allowLinking="true" />


<Context path="/" docBase="/usr/lib/xwiki" privileged="true" crossContext="true">
  <!-- make symlinks work in Tomcat -->
  <Resources allowLinking="true" />

Don’t forget to start Tomcat again:

systemctl start tomcat8.service

Now the URL is simply:


Enable superadmin

This is needed if you plan to import XWiki pages from a previous installation.

vim /etc/xwiki/xwiki.cfg

Find the following section.

#-# Enable to allow superadmin. It is disabled by default as this could be a
#-# security breach if it were set and you forgot about it. Should only be enabled
#-# for recovering the Wiki when the rights are completely messed.
# xwiki.superadminpassword=system

….and change to:

#-# Enable to allow superadmin. It is disabled by default as this could be a
#-# security breach if it were set and you forgot about it. Should only be enabled
#-# for recovering the Wiki when the rights are completely messed.

Don’t forget to restart Tomcat if necessary.

Update Cookie Encryption Keys

When a user logs in, three cookies are saved to their machine. These cookies are encrypted with the below details. First we need to get the two random strings of equal length.

root@wiki:~# date +%s | sha256sum | base64 | head -c 32 ; echo
root@wiki:~# date +%s | sha256sum | base64 | head -c 32 ; echo

Then edit the xwiki.cfg file.

vim /etc/xwiki/xwiki.cfg

Find the relevant section and edit to look like the below.


Don’t forget to restart Tomcat if necessary.

Complete the Installation

Login to complete the installation.

Log in
Log in

Click continue.

Installation wizard
Installation wizard

Register and log in.

Register and login
Register and login


Install xwiki
Install xwiki

Select 9.9 and continue.

Install 9.9
Install 9.9

Confirm installation again.

Confirm installation
Confirm installation



Continue again.

Continue again
Continue again

Confirm the report by clicking continue.

Confirm installation report
Confirm installation report

Installation complete!

Installation Complete
Installation Complete

Import old XWiki Content

Lets see if the import feature works!  Log in as the superadmin user and then navigate to the Administration section:


Then select Content, followed by Import:


Select the backup.xar that you (hopefully) took earlier and import all the content.

Package content
Package content

Select the following options.

Import options
Import options


How to Safely Reduce the Size of a Logical Volume

Do not attempt to shrink a volume if the partition is mounted!  Always unmount first! If it is the root volume you need to reduce in size, use a Live DVD/USB instead. You should also take a backup first too 😉

So here we can see I have one Physical Volume, /dev/md0, attached to my one volume group, RAIDVG.

[andy@home-pc ~]$ sudo pvs
  PV         VG     Fmt  Attr PSize PFree
  /dev/md0   RAIDVG lvm2 a--  1.91t    0

We can also see there is zero space left on the volume group.  You can use sudo pvdisplay to see a more detailed output.

As we can see, all this space is being used up by two Logical Volumes.

[andy@home-pc ~]$ sudo lvs
  LV        VG     Attr       LSize   Pool Origin Data%  Meta%  Move Log Cpy%Sync Convert
  MediaLV   RAIDVG -wi-ao----   1.32t                                                    
  StorageLV RAIDVG -wi-ao---- 600.00g

I can see the filesystem reports I have 664G available.  I am going to play it nice and safe and only attempt to reduce the size of my LV by 400G.

[andy@home-pc ~]$ sudo df -h /dev/RAIDVG/MediaLV 
Filesystem                  Size  Used Avail Use% Mounted on
/dev/mapper/RAIDVG-MediaLV  1.4T  603G  664G  48% /plex

Don’t forget to unmount!

[andy@home-pc ~]$ sudo umount -v /dev/RAIDVG/MediaLV
umount: /plex (/dev/mapper/RAIDVG-MediaLV) unmounted

Check for potential issues.

[andy@home-pc ~]$ sudo e2fsck -f /dev/RAIDVG/MediaLV
e2fsck 1.43.4 (31-Jan-2017)
Pass 1: Checking inodes, blocks, and sizes
Pass 2: Checking directory structure
Pass 3: Checking directory connectivity
Pass 4: Checking reference counts
Pass 5: Checking group summary information
/dev/RAIDVG/MediaLV: 35668/88866816 files (11.1% non-contiguous), 163854225/355446784 blocks

It is very important that you run the --reseizefs operand at the same time.

[andy@home-pc ~]$ sudo lvreduce -L -400G /dev/RAIDVG/MediaLV --resizefs
fsck from util-linux 2.29.2
/dev/mapper/RAIDVG-MediaLV: clean, 35668/88866816 files, 163854225/355446784 blocks
resize2fs 1.43.4 (31-Jan-2017)
Resizing the filesystem on /dev/mapper/RAIDVG-MediaLV to 250589184 (4k) blocks.
The filesystem on /dev/mapper/RAIDVG-MediaLV is now 250589184 (4k) blocks long.

  Size of logical volume RAIDVG/MediaLV changed from 1.32 TiB (347116 extents) to 955.92 GiB (244716 extents).
  Logical volume RAIDVG/MediaLV successfully resized.

Note the (minus) -400G. This means reduce by 400G. If I had used 400G instead, LVM would have made the LV 400G, reducing it from 1.3T.  I would have lost over 200G of actual data. Ouch!

And finally I now have 400G available in my VG.

[andy@home-pc ~]$ sudo pvs
  PV         VG     Fmt  Attr PSize PFree  
  /dev/md0   RAIDVG lvm2 a--  1.91t 400.00g

Be careful and remember to take a backup!


The OpenSSL project is an open-source general purpose cryptography library that implements the SSL and TLS protocols.

Configuration File

The configuration file for OpenSSL is openssl.cnf. The location of which will probably vary across Linux distributions. On Red Hat systems the configuration file is as shown below.


You can use this file to define certain default values. For example, editing the dir variable sets the default directory for saving your certificates. You will need to first create the directory if you change this value.

dir = /certs/ssl/ca

Some additional variables I like to set are as shown below. You might also want to consider entering in this information if you generate a lot of self-signed certificates.

default_days = 3650
default_bits = 2048
countryName_default = US
stateOrProvinceName_default = Washington
localityName_default = Seattle
0.organizationName_default = My Company
commonName_default = example.com
emailAddress_default = root@example.com

By replacing these details with your own, will prevent you from having to enter this information in manually each and every time you create a new CSR (Certificate Signing Request).

More stuff here…

More stuff here…

openssl ....


OpenSSL: Cryptography and SSL/TLS toolkit

Wikipedia: OpenSSL


The locate command can be used to find files by name.

As usual you can find out everything you could possibly want to know about the the locate command in the manual pages.

man locate

Essentially, locate, at set periods runs a cron job indexing each file name into a database. The locate command simply searches the database for a given file name. If you know the file you are searching for is new, you might first need to update the locate database with updatedb.

In its simplest form, to find a file called myfile.txt, run.

locate myfile.txt


You can use the find command to search a system for files or directories. The find command can be quite resource intensive as it trawls recursively through your file structure. Often a more suitable command is locate. See here for more information about the locate command.

As usual you should head to the manual pages to find out more.

man find

In its simplest form, you can use the find command like this.

find / -name myfile.txt

The ‘/’ is the directory to start recursively searching from. We use the ‘-name’ command line option to indicate we are searching on the files name. In this case the string we are searching for is myfile.txt.

Create a Self-Signed Certificate for Apache

Contained within an SSL certificate is information that pertains to you and your secured domain. Lets imaging that you have a web hosting company called Spider and the details for which are shown below.

Country Name (2 letter code):		UK
State or Province Name (full name):	Surrey
Location Name (city):			Camberley
Organisation Name (company):		Spider Web Hosting
Organisation Unit Name (section):	IT Support
Common Name (your domain name):		spiderwebhosting.com
Email Address ():			webmaster@spiderwebhosting.com

A challenge password: 			leave blank
An optional company name: 		leave blank

Generate a Private Key and Certificate Signing Request

Here we generate a Certificate Signing Request and populate it with our details. The -nodes flag tells openssl to create a private key that does not require a pass-phrase. Emitting this flag will prompt for a pass-phrase every time you use it. If installing it on Apache, this will mean entering it every time the Apache service is restarted.

openssl req -new -nodes > spiderwebhosting.com.csr

The above command will generate the CSR and the private key in your current directory.


Generate the Certificate

To generate a certificate, you need a Certificate Signing Request and a private key. The output of the below command will create a certificate valid for 365 days, called spiderwebhosting.com.cert within your current working directory.

openssl x509 -in spiderwebhosting.com.csr -out spiderwebhosting.com.cert -req -signkey privkey.pem -days 365

Make sure that the private key is not world-readable but the certificate is.

chmod go-rwx spiderwebhosting.com.cert

The above command removes read, write and execute permissions from the group and other users.


Linux.com: Creating Self-Signed SSL Certificates for Apache on Linux

Hosting.com: Generate a Self-signed SSL in Linux

Unix and Linux System Administration, fourth edition; Nemeth Snyder Hein Whaley.
pages 971-973

The Most Common OpenSSL Commands

What is a Pem file and how does it differ from other OpenSSL Generated Key File Formats?

Generating 2048-bit CSR with OpenSSL

Gentoo: Temporarily Configure Networking

This can be useful if your working from a LiveCD or testing the network. Note, “temporary” means it will not survive a reboot! To configure networking, adjust the below command for your own environment.

ifconfig eth0 broadcast netmask up
route add default gw

The above commands assign the static IP address of to the eth0 interface and defines the default gateway as

You might also need to add some nameservers to your /etc/resolv.conf configuration file.


Again, this configuration will be lost after a reboot. To permanently create these rules, use the /etc/conf.d/net configuration file.