This page details the migration process for upgrading

For logs of past upgrades see UpgradesLog.

General Architecture

There are several Virtual Machines used to serve

  • Solr instance used by XWiki
  • XWiki instance on node 1 of the cluster
  • XWiki instance on node 2 of the cluster
  • database node: Database used by nodes 1 and 2

Nodes 1 and 2 and the SOLR VM need to be upgraded, starting with the Solr one (since the nodes 1 and 2 depend on it).

The guide below explains how to perform an upgrade that results in no downtime for users. Remember that is used not only by users of the website but also by the Extension Manager located in all instances of XWiki around the world!). So when a downtime occurs, it means no ability to upgrade XWiki itself (or extensions) or to install new extensions. It can even mean failing installs and upgrades if goes down after an install or upgrade has been started!

Upgrade Solr

It's possible that the new version of XWiki expects a more recent version of Solr than the one currently installed. In that case you will need to upgrade the Solr server itself. Note that you may also want to upgrade the Solr server without upgrading XWiki just to get some specific Solr improvements/bugfixes.


  1. Ask the infra team for a clone VM of and perform the next steps on that clone. Ask them for the new IP.
  2. Go to /opt/
  3. Download solr
  4. Unzip (or untgz or whatever) it in /opt/
  5. Make /opt/solr target this new folder (sudo ln -s solr-5.3.1 solr)
  6. Restart Solr using /etc/init.d/solr restart

Upgrade SOLR XWiki setup

Only when needed (when solr schema changes).

XWiki core configuration files are located in /usr/local/. You can find the version you need on Replace everything locate in conf subfolder.

cd /usr/local
sudo mkdir solr-xwiki-${VERSION}
cd solr-xwiki-${VERSION}
sudo wget${VERSION}/xwiki-platform-search-solr-server-data-${VERSION}.jar
sudo unzip xwiki-platform-search-solr-server-data-${VERSION}.jar
sudo rm xwiki-platform-search-solr-server-data-${VERSION}.jar
cd ..
chown -R solr.solr solr-xwiki-${VERSION}
sudo /etc/init.d/solr stop
sudo rm solr-xwiki
sudo ln -s solr-xwiki-${VERSION} solr-xwiki
sudo /etc/init.d/solr start

Upgrade XWiki


  1. Release the Flavor. Make sure it's released in Nexus so that it's in
  2. Ask infra team to direct all users to
  3. Stop + stop cluster on it + configure SOLR to point to the new SOLR VM (if a new SOLR VM was needed)

    Stop XWiki by executing:

    sudo /etc/init.d/ maintenance on
    sudo /etc/init.d/ stop

    Stop cluster by editing and commenting out the 2 properties:

    #observation.remote.enabled = true
    #observation.remote.channels = cluster

    Reconfigure SOLR by editing in order to point the IP to the new SOLR VM:

    solr.remote.url=http://<new ip without port>/solr
  4. Configure in readonly mode.

    Create a page with the following content and execute it in preview mode (no need to save):

    def xwiki = xcontext.getXWiki()
    xwiki.isReadOnly = true

    Also modify xwiki.cfg so that if node 1 crashes and restarts the readonly mode stays:

  5. Ask infra team to stop the DB replication + clone the DB VM to a new VM (hint: that takes about 30mn). Ask them the IP of the new DB VM.
  6. Update to point to the new DB VM by editing hibernate.cfg.xml:
    <property name="connection.url">jdbc:mysql://<new DB VM IP>:3306/xwiki?useSSL=false</property>
  7. Upgrade xwiki on
    1. Upgrade the XWiki WAR
      1. Get the latest version of XE web WAR
        export VERSION=<VERSION>
        cd /usr/local/
        sudo wget${VERSION}/xwiki-enterprise-web-${VERSION}.war
        sudo unzip xwiki-enterprise-web-${VERSION}.war -d xwiki-enterprise-web-${VERSION}
        sudo rm xwiki-enterprise-web-${VERSION}.war
      2. Make a symlink to the newly unzipped webapp (if there's already a symlink to, remove it first).
        sudo ln -s xwiki-enterprise-web-${VERSION}
      3. Update configuration
        1. Copy over some configuration files
          sudo cp xwiki/WEB-INF/hibernate.cfg.xml
          sudo cp xwiki/WEB-INF/observation/remote/jgroups/*.xml
        2. Merge some configuration files
          sudo mv; sudo sdiff xwiki/WEB-INF/web.xml -B -W -E -o
          sudo mv; sudo sdiff xwiki/WEB-INF/xwiki.cfg -B -W -E -o
          sudo mv; sudo sdiff xwiki/WEB-INF/ -B -W -E -o
          sudo mv; sudo sdiff xwiki/WEB-INF/struts-config.xml -B -W -E -o
          sudo mv; sudo sdiff xwiki/WEB-INF/classes/logback.xml -B -W -E -o
          Press 'l' to choose the left version (this is the version from the currently installed file) or 'r' for the right version
        3. Configure the flavor. Change 2 things:
          • The artifact id. To do so, edit /usr/local/ and replace


          • The subwiki extension id so that it uses the special flavor. To do so, edit /usr/local/ and replace


        4. Copy some files:
          sudo cp xwiki/WEB-INF/lib/javamelody-*.jar
          sudo cp xwiki/WEB-INF/lib/jrobin-*.jar
        5. Configure banner for readonly mode (this is needed till XWIKI-13198 is implemented) by running sudo vi and adding the following just before the UIX code TODO: Use a UIX in XWiki for this:
          ## Custom addition on 2016-03-11. To be removed in the future when it's implemented in XWiki
          #if ($xwiki.isReadOnly())
           <div style="font-size: 24px;" class="errormessage">This wiki is being upgraded and is in read-only mode for the moment. It'll be back in edit mode soon. Sorry for the inconvenience</div>
          ## End of custom addition
      4. Make sure the right permissions are set
        sudo chown -R tomcat:tomcat xwiki-enterprise-web-${VERSION}
        sudo find -type f -exec chmod 664 {} \;
        sudo find -type d -exec chmod 775 {} \;
        cd ..
      5. Replace the xwiki symbolic links and delete symlink
        sudo rm xwiki
        sudo rm
        sudo ln -s xwiki-enterprise-web-${VERSION} xwiki
      6. Activate migrations
        sudo vim xwiki/WEB-INF/xwiki.cfg


      7. Start Tomcat
        ## In another shell execute this to follow the startup
        tail -f /usr/local/tomcat/logs/catalina.out
        ## In the main shell, start Tomcat
        sudo /etc/init.d/ start
    2. Deactivate migrations
      sudo vim xwiki/WEB-INF/xwiki.cfg


    3. Navigate to the home page and upgrade the main wiki, subwikis and extensions.
    4. Make especially sure you upgrade all extensions on the playgroundtemplate wiki and then:
      • Verify that is correctly protected so that only admins can modify it. Also verify that its home page has the following section at the top:
        = Welcome to the Playground =

        This a wiki you can use to try out some of XWiki's features.

        To get started, {{html}}<a href="">Register{{/html}} and then log in. Then make all modifications you want in the [[Sandbox Zone>>Sandbox.WebHome]] or in the [[Blog>>Blog.WebHome]]. Other locations are protected from edition (including this home page) to avoid the wiki from being defaced.

        If you wish to try a fully functional XWiki, including the Administration parts, we recommend signing up for a [[free trial of XWiki Cloud>>]] (Service provided by XWiki SAS, [[one of the companies sponsoring the development of XWiki>>xwiki:Main.Supporters.SponsoringCompanies.WebHome]]).

        Note that this wiki is unmoderated and its content is reset automatically every day (including user accounts).

        ... default content here...
      • Delete the playground wiki using the Wiki Manager
      • Recreate the playground wiki using the Wiki Manager, using playgroundtemplate as the template. Make sure to use as the alias. Allow local and global users.
      • Edit rights on so that:
        • At the wiki level, allow "view", "comment", "edit", "script" and "register" for XWikiAllGroup (both local and global)
        • At the wiki level, allow "view" and "register" for the Guest user
        • For Main, Help, Tour, Dashboard page and children, disallow "edit" for XWikiAllGroup (both local and global)
      • Save a MySQL dump so that this wiki can be reset every day. Ssh to and as root, execute:
        sudo bash -c "mysqldump -uxwiki -p<pass here> --add-drop-database playground > /root/playground/playground.sql"
      • Check the site and verify the reset works by executing the following as root and then verify again the web site:
    5. Disable maintenance mode
      sudo /etc/init.d/ maintenance off
    6. Verify that the main wiki and all subwikis of work fine. Ideas of things to check:
      • Verify that Search works on all subwikis.
      • Verify that the home page of all subwikis displays fine.
      • Verify if registration works fine.
    7. Update the file on to be <VERSION>-node2.
  8. Ask Infra team to switch to node 2, copy the node 2 VM onto the node 1 VM
  9. Enable Scheduler plugin on + enable IRC Bot on it + activate cluster + edit to contain <VERSION>-node1. Restart node1.
  10. Ask Infra team to configure the load balancer to point to node 1.
  11. Stop node2. Configure cluster. Restart it
  12. Ask Infra team to enable both nodes on the load balancer
Created by Vincent Massol on 2007/11/27

Get Connected