XWiki - quick installation of opensource CMS based on java

Last modified by matto on 2018/06/06 04:33

I've been using Joomla CMS many years. Joomla! and PHP are nice, but I think that their time is over. Why? Java technology is much more superior and mature. It's time to ditch PHP and Joomla! This guide combines several guides available at official xwiki website, plus other resources. It's quick and easy way how to have your XWiki up and running within few minutes.

Setting up your linux server

In these days, it's very easy to setup linux based server with public IP.
I'm using linode.com and Ubuntu 16.04 LTS. Version It's currently not possible to make it work on Ubuntu 18.04, due to several problems with tomcat and java.

Installing and configuring such system is out of scope of this article. You should have some basic  linux administration knowlege.

Installing XWiki as debian package

This is the guide how to install xwiki as debian package (Ubuntu 18.04 uses debian packages). 

Login to your linux server as root and execute the following commands:

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/

apt-get update

This will add the xwiki repositories. Then, install xwiki.
I've decided to use Tomcat 8 PostgreSQL. I prefer PostgreSQL rather than MySQL. There are many reasons for that, but are out of scope of this blog post.
Execute the following commands:

apt-get install xwiki-common 

apt-get install xwiki-tomcat8-pgsql

This will install all dependencies including PostgreSQL server. System will ask you to create the postgreSQL user and enter the password. Make sure you use the strong password. It's best to use some password manager, such as keepassx for linux, where you can generate strong random passwords.

less /var/log/tomcat8/catalina.out 

gives an error:

SEVERE: Unable to process Jar entry [module-info.class] from Jar [jar:file:/usr/lib/xwiki/WEB-INF/lib/jaxb-api-2.3.0.jar!/] for annot
org.apache.tomcat.util.bcel.classfile.ClassFormatException: Invalid byte tag in constant pool: 19

To avoid this problem, do the following:

vi /etc/tomcat8/catalina.properties 



and add the following .jar files at the end:



vi /usr/share/tomcat8/bin/catalina.sh 

and add the following lines right after: #!/bin/sh

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

Change default passwords (generate random passwords using keepassx tool, or any other password manager):

vi /etc/xwiki/xwiki.cfg




service tomcat8 restart

Wait few seconds until it loads and then try to open URL:


Here's the expected result:


Follow the instructions and in "Step 2 - Flavor", choose: 


And click "Install this flavor". After few minutes, you have the xwiki installed on your system.
This is now the front page looks like:


All good. You'll notice, that the URL ends with


which is certainly not good in terms of SEO.

Optimizing URLs - removing "/xwiki/"

First of all, we need to remove "/xwiki/". All detailed instructions are here:


Rename file /etc/tomcat7/Catalina/localhost/xwiki.xml into /etc/tomcat8/Catalina/localhost/ROOT.xml

Edit file /etc/xwiki/xwiki-tomcat8.xml and change path="/xwiki" to path="/"

Edit /etc/xwiki/xwiki.cfg and uncomment xwiki.webapppath=

Now, let's restart tomcat again to check if we got rid of "/xwiki/" suffix.

service tomcat8 restart

This is the result: 


Better! Still, we need to get rid of "/bin/view/Main/".

Optimizing URL - removing "/bin/view/Main/"

Detailed instructions are at this URL:


In short: 

download URL Rewrite filter .jar file from: http://www.tuckey.org/urlrewrite/ 

cd ..
vi web.xml

Put the following snippet before the first <filter> tag:


Edit urlrewrite.xml (in /usr/lib/xwiki/WEB-INF):

vi urlrewrite.xml

Place there content from:


<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE urlrewrite PUBLIC "-//tuckey.org//DTD UrlRewrite 4.0//EN"
<urlrewrite decode-using="null">

     Ensure that URLs ending with .gwtrpc are not modified.
     Note: Not needed with XWiki 9.7+ since the GWT editor has been removed.
   <to type="forward" last="true">-</to>

      Ensure that URLs that must not be served by the Struts Servlet are not modified.
   <to type="forward" last="true">-</to>

      For all other URLs we prepend the "/bin/" prefix so that they get routed to the XWiki Action Servlet.
   <to type="forward">/bin/$1</to>

      Rewrite outbound URLs to remove the "/bin" part when there are two paths after it.

      Rewrite outbound URLs to remove the "/bin" part when there's a single path after it.

      Rewrite outbound URLs to remove the "/bin" part it's the last path.


Removing "/view/"

vi /etc/xwiki/xwiki.cfg 



Let's try it out:

service tomcat8 restart

This is the result:


Great! These URLs are now search engine optimized.

Installing nginx reverse proxy

There are many reasons, why users should not connect directly to Tomcat. It's better to use a reverse proxy, some of the reasons are listed here: https://en.wikipedia.org/wiki/Reverse_proxy

detailed instructions are here:


We also want our XWiki installation to be available via HTTPs (secured HTTP).

To summarize it, let's install nginx first:

apt install nginx

edit /etc/nginx/sites-available/default

server {
    listen       80;
    server_name  yourserver.com;

    # Normally root should not be accessed, however, root should not serve files that might compromise the security of your server.
    root /var/www/html;

    location ^~ / {
       # If path starts with /xwiki - then redirect to backend: XWiki application in Tomcat
       # Read more about proxy_pass: http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass
       proxy_pass http://localhost:8080;
       proxy_set_header        X-Real-IP $remote_addr;
       proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
       proxy_set_header        Host $http_host;
       proxy_set_header        X-Forwarded-Proto $scheme;

service nginx restart

Now try to access your blog on standard port :80 (http)



Voila! It works. Now, we need to setup HTTPs 

Setting up HTTPs certificate for your XWiki

We will use "Letsencrypt" HTTPs certificate provider, which issues free HTTPs certificates with limited validity (it's possible to renew it every time).

apt install letsencrypt

First, we need to stop nginx temporarily.  

service nginx stop

Then, we need to obtain a HTTPs certificate (replace yourserver.com with your actual server domain name): 

letsencrypt certonly --standalone -d yourserver.com

After entering email address, you will see the following screen:


This means, that certificates have been placed in the /etc/letsencrypt/ folder.

Now, we need to tell nginx where to find them.

mkdir /var/log/nginx-xwiki/

vi /etc/nginx/sites-available/default

make sure it looks like:

server {
    listen      80;
    server_name yourserver.com;

    location ~ /.well-known {
        allow all;

   rewrite     ^   https://$server_name$request_uri? permanent;

   access_log /var/log/nginx-xwiki/access.log;
   error_log /var/log/nginx-xwiki/error.log;


server {
    listen      443;
    server_name yourserver.com;

    root /var/www/html;

    ssl on;
    ssl_certificate /etc/letsencrypt/live/yourserver.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourserver.com/privkey.pem;

    access_log /var/log/nginx-xwiki/access_ssl.log;
    error_log /var/log/nginx-xwiki/error_ssl.log;

    location / {
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forward-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Scheme $scheme;
        proxy_redirect off;
        if (!-f $request_filename) {

   location ~ /.well-known {
        allow all;

vi /etc/tomcat8/server.xml

Right after <Engine .. > add the following lines:

  <Valve className="org.apache.catalina.valves.RemoteIpValve"



We will only allow access to port 8080 from localhost (by nginx). Find:

<Connector port="8080"

make sure to add: 

 <Connector port="8080" protocol="HTTP/1.1"



service tomcat8 restart

Now, try to access your site via HTTPs. There is green lock and all content has been loaded via HTTPs.


That's it ! emoticon_smile

Now, feel free to add new content to your XWiki blog.

Next steps, which you should do, is that you install some firewall (csf firewall is recommended), but this is out of scope of this article.

Created by matto on 2018/05/21 11:39
CodeGravity.com ©
Analytics Made Easy - StatCounter