This article is outdated and may not work correctly for current operating systems or software.
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.
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.
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
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
Distribution Wizard" web interfaceAt 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.
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.
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/.