Migration Process

Last modified by Thomas Mortagne on 2017/03/24

This page details the migration process for upgrading xwiki.org.

For logs of past upgrades see UpgradesLog.

General Architecture

There are several Virtual Machines used to serve xwiki.org:

  • solr.xwiki.org: Solr instance used by XWiki
  • xwikiorg-node1.xwikisas.com: XWiki instance on node 1 of the cluster
  • xwikiorg-node2.xwikisas.com: 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 xwiki.org 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 xwiki.org 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 solr.xwiki.org 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 http://maven.xwiki.org/releases/org/xwiki/platform/xwiki-platform-search-solr-server-data/. Replace everything locate in conf subfolder.

cd /usr/local
sudo mkdir solr-xwiki-${VERSION}
cd solr-xwiki-${VERSION}
sudo wget http://maven.xwiki.org/releases/org/xwiki/platform/xwiki-platform-search-solr-server-data/${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 ..
sudo /etc/init.d/solr stop
sudo rm solr-xwiki
sudo ln -s solr-xwiki-${VERSION} solr-xwiki
sudo chown -R solr:solr solr-xwiki-${VERSION}
sudo /etc/init.d/solr start

Upgrade XWiki


  1. Release the XWiki.org Flavor. Make sure it's released in Nexus so that it's in maven.xwiki.org.
  2. Ask xwiki.org infra team to direct all users to xwikiorg-node1.xwikisas.com
  3. Stop xwikiorg-node2.xwikisas.com + 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/xwiki.sh maintenance on
    sudo /etc/init.d/xwiki.sh stop

    Stop cluster by editing xwiki.properties and commenting out the 2 properties:

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

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

    solr.remote.url=http://<new ip without port>/solr
  4. Configure xwikiorg-node1.xwikisas.com 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 xwiki.org 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 xwikiorg-node2.xwikisas.com 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 xwikiorg-node2.xwikisas.com
    1. Upgrade the XWiki WAR
      1. Get the latest version of XE web WAR
        export VERSION=<VERSION>
        cd /usr/local/
        sudo wget http://maven.xwiki.org/releases/org/xwiki/enterprise/xwiki-enterprise-web/${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 xwiki.new, remove it first).
        sudo ln -s xwiki-enterprise-web-${VERSION} xwiki.new
      3. Update configuration
        1. Copy over some configuration files
          sudo cp xwiki/WEB-INF/hibernate.cfg.xml xwiki.new/WEB-INF/
          sudo cp xwiki/WEB-INF/observation/remote/jgroups/*.xml  xwiki.new/WEB-INF/observation/remote/jgroups/
        2. Merge some configuration files
          sudo mv xwiki.new/WEB-INF/web.xml xwiki.new/WEB-INF/web.xml.ori; sudo sdiff xwiki/WEB-INF/web.xml xwiki.new/WEB-INF/web.xml.ori -B -W -E -o xwiki.new/WEB-INF/web.xml
          sudo mv xwiki.new/WEB-INF/xwiki.cfg xwiki.new/WEB-INF/xwiki.cfg.ori; sudo sdiff xwiki/WEB-INF/xwiki.cfg xwiki.new/WEB-INF/xwiki.cfg.ori -B -W -E -o xwiki.new/WEB-INF/xwiki.cfg
          sudo mv xwiki.new/WEB-INF/xwiki.properties xwiki.new/WEB-INF/xwiki.properties.ori; sudo sdiff xwiki/WEB-INF/xwiki.properties xwiki.new/WEB-INF/xwiki.properties.ori -B -W -E -o xwiki.new/WEB-INF/xwiki.properties
          sudo mv xwiki.new/WEB-INF/struts-config.xml xwiki.new/WEB-INF/struts-config.xml.ori; sudo sdiff xwiki/WEB-INF/struts-config.xml xwiki.new/WEB-INF/struts-config.xml.ori -B -W -E -o xwiki.new/WEB-INF/struts-config.xml
          sudo mv xwiki.new/WEB-INF/classes/logback.xml xwiki.new/WEB-INF/classes/logback.xml.ori; sudo sdiff xwiki/WEB-INF/classes/logback.xml xwiki.new/WEB-INF/classes/logback.xml.ori -B -W -E -o xwiki.new/WEB-INF/classes/logback.xml
          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 xwiki.org flavor. Change 2 things:
          • The artifact id. To do so, edit /usr/local/xwiki.new/META-INF/extension.xed and replace


          • The subwiki extension id so that it uses the special xwiki.org flavor. To do so, edit /usr/local/xwiki.new/META-INF/extension.xed and replace


        4. Copy some files:
          sudo cp xwiki/WEB-INF/lib/javamelody-*.jar xwiki.new/WEB-INF/lib
          sudo cp xwiki/WEB-INF/lib/jrobin-*.jar xwiki.new/WEB-INF/lib
        5. Configure banner for readonly mode (this is needed till XWIKI-13198 is implemented) by running sudo vi xwiki.new/skins/flamingo/global.vm 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}
        cd xwiki.new
        sudo find -type f -exec chmod 664 {} \;
        sudo find -type d -exec chmod 775 {} \;
        cd ..
      5. Replace the xwiki symbolic links and delete xwiki.new symlink
        sudo rm xwiki
        sudo rm xwiki.new
        sudo ln -s xwiki-enterprise-web-${VERSION} xwiki
      6. Activate migrations
        sudo vim xwiki/WEB-INF/xwiki.cfg

        Set xwiki.store.migration=1

      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/xwiki.sh start
    2. Deactivate migrations
      sudo vim xwiki/WEB-INF/xwiki.cfg

      Set xwiki.store.migration=0

    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 playgroundtemplate.xwiki.org 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="http://playground.xwiki.org/xwiki/bin/register/XWiki/Register">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>>http://www.xwiki.com/en/products/try-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 playground.xwiki.org as the alias. Allow local and global users.
      • Edit rights on http://playground.xwiki.org 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 xwikiorg-db.xwikisas.com 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/xwiki.sh maintenance off
    6. Verify that the main wiki and all subwikis of xwiki.org 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 version.properties file on xwikiorg-node2.xwikisas.com to be <VERSION>-node2.
  8. Ask Infra team to switch xwiki.org to node 2, copy the node 2 VM onto the node 1 VM
  9. Enable Scheduler plugin on xwikiorg-node1.xwikisas.com + enable IRC Bot on it + activate cluster + edit version.properties 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