With Confluence migrating to a full cloud solution and no longer supporting small user deployments, I’ve been pushed into looking at other solutions. In looking around, I liked the support surrounding Xwiki, plus I use Xwiki at work so there is familiarity to the syntax language.
To setup Xwiki, I needed to configure an RDMS and java servlet engine. Xwiki will work with a wide range of database engines and java servlet engines. For RDMS I chose mariadb and tomcat for the java servlet.
MariaDB Setup
First install the database engine:
yum install mariadb mariadb-server
Start the database and enable it on reboot:
systemctl start mariadb.service
systemctl enable mariadb.service
Log into the database.
mysql -u root
Create a database for the wiki:
create database xwiki default character set utf8;
Create a user for the application to use in accessing the database: (of course use a better password!)
create user 'wiki'@localhost identified by 'xwiki';
Grant this user access to the xwiki database:
grant all privileges on *.* to 'xwiki'@localhost indentified by 'xwiki';
You can double check the grants are correctly applied with:
show grants for 'xwiki'@localhost;
Java Setup
You need to make sure you select a java version that works with a specific version of tomcat and is supported by the Xwiki application. At the time of this writing, Java 8, Tomcat 8 and Xwiki 12.10.10 all work together.
Installing Java 8:
yum install java-1.8.0
Verify the install and version by running at the command line:
java -version
The response back should be similar to the following:
openjdk version "1.8.0_302"
OpenJDK Runtime Environment (build 1.8.0_302-b08)
OpenJDK 64-Bit Server VM (build 25.302-b08, mixed mode)
Open Firewall Port
Xwiki runs on port 8080/tcp and you’ll need to open the firewall port.
firewall-cmd --permanent --add-port 8080/tcp
firewall-cmd --reload
Tomcat Install
First thing to do is create a group and user for tomcat to run under:
sudo groupadd tomcat
sudo useradd -g tomcat -d /opt/tomcat tomcat
The download tomcat 8 from tomcat.apache.org. Make sure you are downloading the version of tomcat you decided to run. Its easy to download an incorrect version which will drive you nuts later on. (ask me how I know) Also download the tar.gz version, as it preserves file attributes.
Upload Tomcat 8 to the /opt directory and uncompress it. gzip -d and tar -xf will get the job done. I then remove the /opt/tomcat directory and rename the /opt/apache-tomcat-8.5.72 directory to /opt/tomcat. I update the group and owner on the /opt/tomcat directory to make sure the tomcat user has full access to the servlet.
chgrp -R /opt/tomcat
chown -R /opt/tomcat
You should double check the file attributes in the /opt/tomcat/bin directory. All of the *.sh files should be set executable. If not run the following command:
chmod +x /opt/tomcat/bin
Create the Service Wrapper
Creating a service wrapper allows for systemctl to start / stop / restart the tomcat servlet. Create the file tomcat.service in the /etc/systemd/system/ directory. Copy and paste the following code:
[Unit]
Description=Apache Tomcat 8 Service
After=syslog.target network.target
[Service]
Type=forking
User=tomcat
Group=tomcat
Environment=JAVA_HOME=/usr/lib/jvm/jre
Environment=CATALINA_PID=/opt/tomcat/temp/tomcat.pid
Environment=CATALINA_HOME=/opt/tomcat
Environment=CATALINA_BASE=/opt/tomcat
Environment='CATALINA_OPTS=-Xms512M -Xmx1024M -XX:MaxPermSize=192m -server -XX:+UseParallelGC'
Environment='JAVA_OPTS=-Djava.awt.headless=true -Djava.security.egd=file:/dev/./urandom'
ExecStart=/opt/tomcat/bin/startup.sh
ExecStop=/bin/kill -15 $MAINPID
[Install]
WantedBy=multi-user.target
After saving the file, run the following commands to start the tomcat service:
systemctl daemon-reload
systemctl start tomcat.service
To have the tomcat service start on boot up remember to enable it:
systemctl enable tomcat.service
Configure Xwiki
Copy the xwiki-platform-distribution-war-13.8.war file to /opt/tomcat/webapps/xwiki.war. Restart the tomcat service.
systemctl restart tomcat.service
Copy the mariadb JDBC driver jar file into the Xwiki library folder. The folder should be /opt/tomcat/webapps/xwiki/WEB-INF/lib/. I found the mariadb driver their downloads page. I used the most current stable version, which at this writing is version 2.7.3,
Edit the hibernate.cfg.xml file that is located in xwiki/WEB-INF directory. This file provides the connection strings to the database we created earlier. Make sure to comment out the hsqldb section. By default Xwiki comes with this section enabled. I provided the section to comment out:
<!--
<property name="hibernate.connection.url">jdbc:hsqldb:file:${environment.permanentDirectory}/database/xwiki_db;shutdown=true</property>
<property name="hibernate.connection.username">sa</property>
<property name="hibernate.connection.password"></property>
<property name="hibernate.connection.driver_class">org.hsqldb.jdbcDriver</property>
<property name="hibernate.connection.charSet">UTF-8</property>
<property name="hibernate.connection.useUnicode">true</property>
<property name="hibernate.connection.characterEncoding">utf8</property>
<mapping resource="xwiki.hbm.xml"/>
<mapping resource="feeds.hbm.xml"/>
<mapping resource="instance.hbm.xml"/>
<mapping resource="notification-filter-preferences.hbm.xml"/>
<mapping resource="mailsender.hbm.xml"/>
-->
Then uncomment the mariadb section. Update the user name and password that your created when setting up the database.
<!-- MariaDB configuration.
Uncomment if you want to use MariaDB and comment out other database configurations.
Notes:
- if you want the main wiki database to be different than "xwiki"
you will also have to set the property xwiki.db in xwiki.cfg file
-->
<property name="hibernate.connection.url">jdbc:mariadb://localhost/xwiki?useSSL=false</property>
<property name="hibernate.connection.username">xwiki</property>
<property name="hibernate.connection.password">xwiki</property>
<property name="hibernate.connection.driver_class">org.mariadb.jdbc.Driver</property>
<property name="hibernate.dbcp.poolPreparedStatements">true</property>
<property name="hibernate.dbcp.maxOpenPreparedStatements">20</property>
<property name="hibernate.connection.charSet">UTF-8</property>
<property name="hibernate.connection.useUnicode">true</property>
<property name="hibernate.connection.characterEncoding">utf8</property>
<mapping resource="xwiki.hbm.xml"/>
<mapping resource="feeds.hbm.xml"/>
<mapping resource="instance.hbm.xml"/>
<mapping resource="notification-filter-preferences.hbm.xml"/>
<mapping resource="mailsender.hbm.xml"/>
Create Permanent Directory
Xwiki needs a directory for storing attachments and other files. You want these files to be out side of the Xwiki application area. I use /var/lib/xwiki/data for this storage. I then set the owner and group to the tomcat user/group.
chgrp -R tomcat xwiki
chown -R tomcat xwiki
In the /opt/tomcat/webapps/xwiki/WEB-INF directory modify the xwiki.properties file. uncomment the environment.permanentDirectory and make it point to the correct location you have chosen.
Your Ready to Access Xwiki!
XWiki runs on port 8080. To access your XWiki installation open your web browser and type: http://yourdomain_or_ip_address:8080/xwiki
The first time launching Xwiki., the setup script will run. The tables in the database will be created and you’ll setup amoungst other things, the administrator id and password.