Information

XWiki is a next generation wiki, a generic web development platform for collaborative applications. In this guide we will setup XWiki in a Windows 2016 environment on tomcat with a MSSQL 2016 backend.

Server Setup

• Deploy a Windows 2016 Server image/machine using standard template (this is assuming DB hosted on external server)
  • 4 vcpu
  • 8GB Ram
• Configure pagefile drive (E:\) 12GB
• Add new 50GB disk to host the application (E:\)
• Download and install latest java8 64bit offline installer
• Create a service account to be used for tomcat & office services and add to admins group for that server (e.g. svcxwiki01). If you do not wish to add the service account as a local admin you can probably get by if you grant the user modify permissions on all the directories used below.

Database Setup

• Create or have your DBAs create database “xwiki” and grant dbo access to service account
• For MSSQL the server AND the database have to be case-sensitive collation (Latin1_General_CS_AS), DBA’s will know what this means (basically collation set at time of install)
• Optionally, create DNS aliases as needed for the SQL machine that will be used to host the app DB (e.g. sqlprdxwiki.xyz.com)

Tomcat/XWiki Setup

• Download and Install tomcat 9 as windows service, update install path to E:\ (e.g. E:\Apache Software Foundation\Tomcat 9.0)
  • It should pickup the install java path otherwise make sure its installed
• Edit <tomcatinstallpath>/conf/server.xml
  • Update connector ports (change 8080 references to 80 for initial configuration, setup ssl later)
• Stop tomcat
• Run <tomcatinstallpath>/bin/javaw.exe
  • Under “Java” bump up the initial and max memory pool based on the server memory available. Be sure to leave 1-2GB RAM available for the system (this assumed 8GB server).
• Download the latest xwiki.war from xwiki.org (10.9 currently)
  • Rename the download file to ROOT.war
  • Copy ROOT.war to <TomcatInstallPath>\webapps\

• Delete existing root folders
  • <TomcatInstallPath>\webapps\ROOT
  • <TomcatInstallPath>\work\catalina\localhost\ROOT
• Start tomcat and wait a minute, this will extract ROOT.war as the new root app
• Stop tomcat
• Add <TomcatInstallPath> to windows defender exclusion (seems to cause high cpu)?
• Locate and edit the properties of the windows tomcat service:
  • Set Log On User to your service account (e.g. svcxwiki01@xyz.com)
  • Set service to start automatically
• Edit <TomcatInstallPath>\webapps\ROOT\WEB-INF\hibernate.cfg.xml
  • Comment out existing db config (hyper something)
  • Underneath insert the MSSQL DB config below using correct DNS alias for your DB server such as sqlprdxwiki.dyz.com or sqlstgxwiki.dyz.com
    • Integrated security is used so it will authenticate as the service account configured to start the tomcat service

<property name="connection.url">jdbc:sqlserver://SQLPRDXWIKI.xyz.com:1433;DatabaseName=xwiki;integratedSecurity=true;</property>
<property name="connection.driver_class">com.microsoft.sqlserver.jdbc.SQLServerDriver</property>
<property name="dialect">org.hibernate.dialect.SQLServerDialect</property>
<property name="connection.provider_class">com.xpn.xwiki.store.DBCPConnectionProvider</property>
<property name="connection.pool_size">2</property>
<property name="statement_cache.size">2</property>
<mapping resource="xwiki.mssql.hbm.xml"/>
<mapping resource="feeds.hbm.xml"/>
<mapping resource="activitystream.hbm.xml"/>
<mapping resource="notification-filter-preferences.hbm.xml"/>
<mapping resource="mailsender.hbm.xml"/>

• Download the official Microsoft jdbc driver 6.4 and extract somewhere temporarily (note I had to use 6.4.0 as 7 did not work properly)
• Copy jdbc_xxx.jar from the extract location that matches installed jre version (example mssql-jdbc-6.4.0.jre8.jar) to <TomcatInstallPath>\webapps\ROOT\WEB-INF\lib
• Copy sqljdbc_auth.dll from the extract location and copy to c:\windows\system32 (or add it to PATH but this way is easier)
• Create an XWikiFiles directory outside of the tomcat directory (example E:\XWikiFiles) – this will be used as the perm directory for XWiki

• Update the following options in <TomcatInstallPath>\webapps\ROOT\WEB-INF\xwiki.properties
  • environment.permanentDirectory=E:\XWikiFiles
• Update the following options in <TomcatInstallPath>\webapps\ROOT\WEB-INF\xwiki.cfg
  • xwiki.webapppath= (yes nothing is there, IE be ROOT)
• Delete the <TomcatInstallPath>\work\Catalina\localhost\ directory
• Start tomcat (wait 1min)
• Open a browser and connect to the tomcat port specified (http:\\localhost:80), you should get the xwiki distribution wizard (install wizard)
• Create admin account “Xwiki Admin, username admin, password admin (or whatever)”
• Select Xwiki Standard flavor, Install/continue (will take a few)
• Hit next/ok if necessary until complete

Install complete

Verify your installation is running well with the base flavor.

Open/Libre Office

• Download & install libreoffice or openoffice. You can use either and examples are shown below for both, for this install I used LibreOffice
• Download 2003 resource kit and get the srvany.exe executable (or get it from somewhere else you may have it)
  • Copy srvany.exe to c:\windows\system32 of the server
• Create the windows service (note copy/paste may not work)
  • For Openoffice: sc create “ooservice” binPath= “\”C:\Windows\System32\srvany.exe\”” DisplayName= “OpenOffice Server” start= auto
  • For Libreoffice: sc create “loservice” binPath= “\”C:\Windows\System32\srvany.exe\”” DisplayName= “LibreOffice Server” start= auto
• Navigate to the key HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\services\(loservice or ooservice)
  • Create a new key named “Parameters”.
    • For the new key “Parameters”, create a string value named “Application” with following value.
      • For Openoffice: “C:\Program Files (x86)\OpenOffice 4\program\soffice.exe” -headless -accept=”socket,host=127.0.0.1,port=8100;urp;” -nofirststartwizard
      • For Libreoffice: “C:\Program Files\LibreOffice\program\soffice.exe” -headless -accept=”socket,host=127.0.0.1,port=8100;urp;” -nofirststartwizard -nologo
• Update the service Log On account to the service account used previously (e.g. svcxwiki01@xyz.com)
• Start the new office service and set it to automatic startup
• Update the following lines in <TomcatInstallPath>\webapps\ROOT\xwiki.properties
  • openoffice.serverType=1
  • openoffice.autoStart=true

Customization

Additional Setup

SSL Setup/Tomcat Tuning

• Get or general a cert from your CA (make sure to specify SAN/DNS attributes), then export somewhere with the private key
• Create a java keystore from using the cert (just remake it from scratch each time, don’t use/overwrite an existing one)
  • Open command prompt and browse to your installed java/bin location then run:
    C:\Program Files\Java\jre1.8.0_171\bin>keytool -importkeystore -srckeystore c:\mycertpath\mpl1itswik001.pfx -srcstoretype pkcs12 -destkeystore c:\users\user\desktop\ssl_java_keystore.jks -deststoretype JKS
• Put keystore file somewhere near tomcat but not in your application directory (such as E:\Apache Software Foundation)
• Edit <tomcatinstallpath>\conf\server.xml and update your connectors

<Connector port="80" protocol="HTTP/1.1" connectionTimeout="2000" redirectPort="443" />
 
<Connector protocol="org.apache.coyote.http11.Http11Nio2Protocol"
port="443" maxThreads="200" connectionTimeout="2000"
scheme="https" secure="true" SSLEnabled="true"
keystoreFile="E:\Apache Software Foundation\ssl_java_keystore.jks" keystorePass="mykeystorepassword"
SSLVerifyClient="optional" SSLProtocol="TLSv1+TLSv1.1+TLSv1.2"
compression="on" compressionMinSize="1024"
noCompressionUserAgents="gozilla, traviata"
compressableMimeType="text/html,text/xml"/>

• Edit tomcatpath\conf\WEB-INF\web.xml
  • Before the very last line (</web-app>) put this to force ssl

<security-constraint>
<web-resource-collection>
<web-resource-name>ROOT</web-resource-name>
<url-pattern>/*</url-pattern>
</web-resource-collection>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>

• Restart tomcat and test SSL (https://servername)

LDAP Setup

• Administer Wiki > Extensions > Extensions, search ldap / all extensions
• Install ldap authenticator & ldap application
• Back to Administer wiki > Other > LDAP
• Edit ldap settings add the following depending on your environment
  • LDAP Server Address: <domaincontroller>
  • LAP Server Port: 389
  • LDAP Login Matching: DOMAIN\{0}
  • LDAP Password Matching: {1}
  • LDAP Base DN: “dc=domain,dc=com”
  • LDAP UID Attrib: sAMAccountName
  • Try Local Login: Yes
  • LDAP User Field Mappings
    • name: sAMAccountName
    • first_name: givenName
    • last_name: sn
    • fullname: displayName
    • email: mail
    • ldap_dn: dn
  • Group Mappings
    • XWiki.MyDomainGroup: CN=MyDomainGroup,OU=Groups,DC=domain,DC=com
  • Group Cache Timeout: 3600
  • Synchronize at each user auth
• Save
• Edit tomcat\webapps\root\web-inf\xwiki.cfg and update the following param

  • xwiki.authentication.authclass=org.xwiki.contrib.ldap.XWikiLDAPAuthServiceImpl

• Save restart tomcat

SSO Setup

• First change your LDAP settings to use the service account and credentials to query (instead of Domain\{0}/{1})
• Download waffle 1.9
  • Copy waffle files to tomcat install path/lib (E:\Apache Software Foundation\Tomcat 9.0\lib):
    • Waffle.Windows.AuthProvider.msm
    • Waffle.Windows.authProvider.dll
    • Waffle-tomcat9-1.9.0.jar
    • Slf4j-api-1.7.25.jar
    • Waffle-jna-1.9.0.jar
    • Jna-platform-4.5.1.jar
    • Jna-4.5.1.jar
    • Caffeine-2.6.2.jar
• Edit and add to end of <TomcatInstallPath>/webapps/ROOT/web-inf/xwiki.cfg:

• Add to the beginning of <TomcatInstallPath>/webapps/ROOT/web-inf/web.xml after <descrpition> (this usually has to be first)

<!-- Begin Polaris Change -->
<filter>
<filter-name>SecurityFilter</filter-name>
<filter-class>waffle.servlet.NegotiateSecurityFilter</filter-class>
<init-param>
<param-name>principalFormat</param-name>
<param-value>fqn</param-value>
</init-param>
<init-param>
<param-name>roleFormat</param-name>
<param-value>both</param-value>
</init-param>
<init-param>
<param-name>waffle.servlet.spi.NegotiateSecurityFilterProvider/protocols</param-name>
<param-value>
NTLM
</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>SecurityFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
<!-- End Polaris Change -->

• Restart tomcat
• Test SSO (make sure the site is added to the “intranet” zone of IE trusted sites)
• Login as a user you plan to make an admin

<you can use firefox or a non NTLM PTA browser to login as admin and grant roles, otherwise you have to disable PTA to be able to login as local admin>

• Stop tomcat
• Update filter in web.xml “<url-pattern>/*</url-pattern>” to “<url-pattern>/random*</url-pattern>”
• Restart tomcat
• Login to wiki as admin, add the previously SSO user as admin account.
• Change filter back to “<url-pattern>/*</url-pattern>”
• Restart tomcat
• Login with your SSO admin account

LDAP Debugging (troubleshooting)

• Add to <TomcatInstallPath>/webapps/ROOT/WEB-INF/classes/logback.xml
  • <!– LDAP debugging –>
  • <logger name=”org.xwiki.contrib.ldap” level=”trace”/>
• Add to <TomcatInstallPath>/conf/logging.properties:
  • waffle.apache.NegotiateAuthenticator.level = FINE

Short URL

This is to shorten the url a bit by removing /bin etc.

• Download rewrite module: urlrewritefilter-4.0.3 – locate the .jar and put in <TomcatInstallPath>/webapps/ROOT/web-inf/lib
• Edit <TomcatInstallPath>/webapps/ROOT/WEB-INF/web.xml
  • Put the following in the beginning after description, if using the SSO/security filter put after the end of its </filter-mapping> since it needs to be first

<!-- Begin Mod rewrite -->
<filter>
<filter-name>UrlRewriteFilter</filter-name>
<filter-class>org.tuckey.web.filters.urlrewrite.UrlRewriteFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>UrlRewriteFilter</filter-name>
<url-pattern>/*</url-pattern>
<dispatcher>REQUEST</dispatcher>
<dispatcher>FORWARD</dispatcher>
</filter-mapping>
<!-- End Mod rewrite -->

• Edit/create <TomcatInstallPath>/webapps/ROOT/web-inf/urlrewrite.xml

<!DOCTYPE urlrewrite PUBLIC "-//tuckey.org//DTD UrlRewrite 4.0//EN"
 "http://www.tuckey.org/res/dtds/urlrewrite4.0.dtd">
<urlrewrite decode-using="null">
 
 <rule>
 <note>
 Ensure that URLs ending with .gwtrpc are not modified.
 Note: Not needed with XWiki 9.7+ since the GWT editor has been removed.
 </note>
 <from>^/(.*)\.gwtrpc$</from>
 <to type="forward" last="true">-</to>
 </rule>
 
 <rule>
 <note>
 Ensure that URLs that must not be served by the Struts Servlet are not modified.
 </note>
 <from>^/((bin|resources|skins|rest|webdav|xmlrpc|wiki|webjars)/(.*)|robots\.txt)$</from> 
 <to type="forward" last="true">-</to>
 </rule>
 
 <rule>
 <note>
 For all other URLs we prepend the "/bin/" prefix so that they get routed to the XWiki Action Servlet.
 </note>
 <from>^/(.*)$</from>
 <to type="forward">/bin/$1</to>
 </rule>
 
 <outbound-rule>
 <note>
 Rewrite outbound URLs to remove the "/bin" part when there are two paths after it.
 </note>
 <from>/bin/(.*)/(.*)$</from>
 <to>/$1/$2</to>
 </outbound-rule>
 
 <outbound-rule>
 <note>
 Rewrite outbound URLs to remove the "/bin" part when there's a single path after it.
 </note>
 <from>/bin/(.*)$</from>
 <to>/$1</to>
 </outbound-rule>
 
 <outbound-rule>
 <note>
 Rewrite outbound URLs to remove the "/bin" part it's the last path.
 </note>
 <from>/bin$</from>
 <to>/</to>
 </outbound-rule>
 
</urlrewrite>

• Restart tomcat/test

Backup & Restore

It is recommended to create a backup script of your config (web-inf\*.xml) and custom files. If you have installed any custom modules for things like SSO & Short-URL, you need to backup those files as well so they can be restored after upgrading etc.

An example backup file that accounts for MSSQL\SSO\ShortURL (xwiki_config_backup.bat):

SET certpath="E:\Apache Software Foundation"
SET tomcatpath="E:\Apache Software Foundation\Tomcat 9.0"
SET rootpath="E:\Apache Software Foundation\Tomcat 9.0\webapps\ROOT\WEB-INF"
SET backuppath="E:\XWikiConfigBackup"
xcopy %certpath%\*.jks %backuppath% /S /Y
xcopy %tomcatpath%\conf\server.xml %backuppath% /S /Y
xcopy %tomcatpath%\lib\waffle* %backuppath%\lib\ /S /Y
xcopy %tomcatpath%\lib\jna* %backuppath%\lib\ /S /Y
xcopy %tomcatpath%\lib\slf4j* %backuppath%\lib\ /S /Y
xcopy %tomcatpath%\lib\caffeine* %backuppath%\lib\ /S /Y
xcopy %rootpath%\hibernate.cfg.xml %backuppath% /S /Y
xcopy %rootpath%\web.xml %backuppath% /S /Y
xcopy %rootpath%\xwiki.cfg %backuppath% /S /Y
xcopy %rootpath%\xwiki.properties %backuppath% /S /Y
xcopy %rootpath%\urlrewrite.xml %backuppath% /S /Y
xcopy %rootpath%\lib\mssql-jdbc-* %backuppath%\lib\ /S /Y
xcopy %rootpath%\lib\urlrewritefilter-* %backuppath%\lib\ /S /Y
pause

Then for convenience a restore script to put the files back (xwiki_config_restore.bat):

SET certpath="E:\Apache Software Foundation"
SET tomcatpath="E:\Apache Software Foundation\Tomcat 9.0"
SET rootpath="E:\Apache Software Foundation\Tomcat 9.0\webapps\ROOT\WEB-INF"
SET backuppath="E:\XWikiConfigBackup"
xcopy %backuppath%\*.jks %certpath% /S
xcopy %backuppath%\server.xml %tomcatpath%\conf\ /S
xcopy %backuppath%\lib\waffle* %tomcatpath%\lib\ /S
xcopy %backuppath%\lib\jna* %tomcatpath%\lib\ /S
xcopy %backuppath%\lib\slf4j* %tomcatpath%\lib\ /S
xcopy %backuppath%\lib\caffeine* %tomcatpath%\lib\ /S
xcopy %backuppath%\web.xml %rootpath% /S
xcopy %backuppath%\hibernate.cfg.xml %rootpath% /S
xcopy %backuppath%\xwiki.cfg %rootpath% /S
xcopy %backuppath%\xwiki.properties %rootpath% /S
xcopy %backuppath%\urlrewrite.xml %rootpath% /S
xcopy %backuppath%\lib\mssql-jdbc-* %rootpath%\lib\ /S
xcopy %backuppath%\lib\urlrewritefilter-* %rootpath%\lib\ /S
pause

Upgrading

• Take snapshot/backup of xwiki vm/database
• Enable schema updates in xwiki.cfg
  • xwiki.store.migration=0
• Backup all config files and live files you’ve added from various modules or use a script (e:\xwiki_config_backup)
• Stop tomcat
• Delete the following:

E:\Apache Software Foundation\Tomcat 9.0\webapps\ROOT
E:\Apache Software Foundation\Tomcat 9.0\work\Catalina\localhost\ROOT
Optionally E:\Apache Software Foundation\Tomcat 9.0\logs\*

• Download latest version and rename/replace current ROOT.war in E:\Apache Software Foundation\Tomcat 9.0\webapps
• Start tomcat, wait about a minute for war file to extract
• Stop tomcat

• If no change restore the config files or use a restore script (e:\wiki_config_restore), when prompted to replace web.xml hit NO – this file shouldn’t be replaced until after the migration due to SSO/modrewrite and some other things we’ve added
• Start tomcat
• Browse to wiki – you should be prompted to login and start the distribution wizard. If there are errors they are almost likely to database upgrade issues which would require checking the logs in the tomcat dir (mssql is not officially supported).
• In the wizard select the latest flavor to upgrade / install. You will then run through the install of all the pages and make have to review any system files that were modified. Most system files such as translations should be replaced with latest version.
• Once upgrade is complete, stop tomcat.
• Copy your web.xml backup or rerun the restore script (e:\xwiki_config_restore) and press yes to everything
• Edit <TomcatInstallPath>\webapps\ROOT\WEB-INF\xwiki.cfg to prevent future upgrades
  • xwiki.store.migration=0
• Start tomcat

After upgrade you may need to rebuild your override templates (using diffs of the new files), templates and skins so that they are based on the current version