Update XStudio VM




Stop the service

Preferably, update your server at a day/time where you're sure nobody will connect.

If this is not possible, it's strongly advised to:
  • Notify the users of an interruption of service
  • Stop the database server

Notify the users of an interruption of service

The first thing to do to avoid loosing some data is to ask all the users to save their data and close their XStudio instances and wait until the update procedure is completed.

Stop the database server

When all the users have saved their data and closed their instances, stop the Database Server service.
This will ensure that nobody can connect anymore.

  • Connect to the VM via Putty (or any other ssh client)
    (by default the root password is rootpwd)
    (alternatively, you can simply connect to the VM directly from the VirtualBox window or Console tab of the vSphere Client, quit the control panel by selecting Advanced Menu, Quit and Select)

  • Run the command service mysql stop


Backup your data

The database

Please refer to your Database Server guide for more information or check out the Backup/Restore section of the documentation.

Your custom launchers

If you developed some custom launchers using the SDK, it's advised to backup all your source files, build scripts, binaries etc. before updating.
You can find all your launcher binaries in:
- the /var/www/xstudio/bin/launchers/ folder if your current version of XStudio is <=3.0.
- the /var/lib/tomcat8/webapps/xqual/xstudio/launchers/ folder if your current version of XStudio is >=3.1.

Your custom reports

If you developed some custom XSLT reports, it's advised to backup all these XSLT (along with their associated resources i.e. images etc.) before updating.
You can find all your custom XSLT reports in:
- the /var/www/xstudio/export.zip file if your current version of XStudio is <=3.0.
- the /var/lib/tomcat8/webapps/xqual/export.zip file if your current version of XStudio is >=3.1.
so just backup this file.

Your visuals

If you customized your server with custom splash screens, logo and icons, it's advised to backup all these resources before updating. You can find all your visuals in:
- the /var/www/xstudio/visuals/ folder if your current version of XStudio is <=3.0.
- the /var/lib/tomcat8/webapps/xqual/visuals/ folder if your current version of XStudio is >=3.1.



Update the server


There are some tools on the VM that are making the update operation very easy, especially if the VM has access to internet.
The internet access is used only to download the new version from our centralized server.

You can test if the VM has access to the internet by doing this:

  • Run the command ping www.xqual.com

update vm ping

If the ping works, then the VM has access to the internet.

Please click on the appropriate options below:


IMPORTANT: If you're updating your VM from a version <3.1b1, you need to install the scripts updater first.

In this case:
  • cd /root
  • wget http://xstudio.alwaysdata.net/support/installation/update_scripts/update_scripts.zip
  • unzip -uo update_scripts.zip
  • chmod a+x *.sh

Then, your update scripts are ok and you can follow the normal instructions below...

To update your VM, you just have to run a couple of scripts.

  • Download the latest version of the updater

    cd /root
    ./update_scripts.sh <version> (i.e ./update_scripts.sh 4.0b3)

  • Download the new version of XStudio, backup your current configuration settings, install the new version and restore the relevant original settings

    ./update_xstudio.sh <version> (i.e /root/update_xstudio.sh 4.0b3)

You have to download manually the new version on the VM at a specific location on the VM.
Then you must run a script that will take care about backuping your current configuration, install the new version and restore the relevant original settings.

  • Connect to the VM as root via WinSCP (or any other similar tool)
    By default the root password is rootpwd

  • Create a folder /root/latest_release/<version> on the server (e.g. mkdir /root/latest_release/3.1sp1) to host the zip file
    (with WinSCP, right-click > New > Directory)

    update vm winscp

    update vm winscp

  • Download the version of the XStudio Web Server package you wish to update to (from our download section)

  • Upload the zip file you downloaded (e.g. xstudio_v12beta3_web_package.zip) in the /root/latest_release/<version>/ folder of the VM
    (with WinSCP, just drag and drop the file in the right panel)

    update vm winscp

  • Unzip the zip file on the VM
    (with WinSCP, right-click on the zip file > Custom Commands > Enter > unzip -o "!")

    update vm winscp

    update vm winscp

    You may be asked to re-authenticate to execute the command remotely:
    update vm winscp

  • Delete the zip file (e.g. xstudio_v12beta3_web_package.zip) in the /root/latest_release/<version>/ folder of the VM
    (with WinSCP, right-click on the zip file > Delete)

    update vm winscp

  • IMPORTANT: If you're updating your VM from a version <3.1b1, you need to install the scripts updater first.

    In this case:
    • cd /root
    • wget http://xstudio.alwaysdata.net/support/installation/update_scripts/update_scripts.zip
    • unzip -uo update_scripts.zip
    • chmod a+x *.sh

  • Edit the standard update script to NOT download the package from the centralized server
    (with WinSCP, move to the /root folder, right-click on the update_xstudio.sh file > Edit and comment the line where the script downloads the package - Line ~14)

    update vm winscp

    update vm winscp

  • Run the command /root/update_xstudio.sh <version> (e.g. /root/update_xstudio.sh 3.1sp1)


Restore your data

Your custom launchers

If you developed some custom launchers using the SDK, and if you are updating to a major version (with changes in the SDK), you need to recompile all of them from their sources using the new SDK and to copy the binaries in the launchers folder (/var/lib/tomcat8/webapps/xqual/xstudio/launchers).
You also need to reference these custom launchers in the /var/lib/tomcat8/webapps/xqual/xstudio/launchers/launchers.xml file.

Your custom reports

If you developed some custom XSLT reports, you need to add them in the new /var/www/xstudio/export.zip file.
This means you must pick the new export.zip file, unzip it, copy your custom XSLT files (along with their associated resources i.e. images etc.) in the structure and rezip it.

Your visuals

If you customized your server with custom splash screens, logo and icons, just check they are still in the /var/www/xstudio/visuals folder (if not, copy your backuped files here).


Restart the service

Restart the database server


  • Run the command service mysql start


Restart Tomcat

To ensure that the REST API server took into account the last changes properly, restart Tomcat.
With Fedora, Cent OS, Red Hat:
service tomcat restart

With Debian, Ubuntu etc.:
service tomcat8 restart

On some particular linux distributions, this can be done by running 2 scripts: shutdown.sh then startup.sh

On Windows this can be done by running the dedicated shutdown.bat and startup.bat scripts or restarting the Windows Service (depends on your Tomcat installation choices)


For debugging purposes, you can have a look at Tomcat's log to check everything started properly without error. The log file is generally located in /var/lib/tomcat8/logs/catalina.out. On recent systems you might get it using the command journalctl -u tomcat.

Start XStudio a first time as admin (mandatory step)

Start normally XStudio from your browser (http://<ip_address>:8080/xqual/xstudio) and log in as admin.
If you're updating to a major version, you MAY be asked again for your admin password to confirm you authorize the system to update the schema of the database. Just confirm and continue.

When the migration is completed, XStudio will re-start normally.

If a schema update was necessary, you can use the database integrity checker available from the menu Tools > Check database integrity to ensure everything's fine.

New mandatory parameters

Also, if some new mandatory parameters are required in *.conf files, a popup will automatically open giving you the opportunity to fill the missing values.
You'll then be able to save the 3 configuration files and upload them to your server.

For instance, if you update from a version <=5 to a version >=6 there will be 3 new parameters to fill in:
  • rest_api.base_url=<REST API server URL> i.e. http://acme-prod1.myxqual.com/xqual/api
  • rest_api.default_username=<XStudio username>
  • rest_api.default_password=<encrypted password>
If some new parameters were required, you'll need to restart Tomcat again so that they are read by the REST API server.

Check the settings and the user profiles

When some new features that need specific rights are added, their associated rights will be missing from the user profiles so these features are disabled "by default".

So when you update, don't forget to check the user profiles to see if you want to add some new rights to some of your profiles.

The same way, in a newer version some of the new features may require some global settings. These settings have all default values but it's a good idea to check those just after an update.

Notify the users that the service is back

Check access to:
- XStudio.web (i.e. http://<ip_address>:8080/xqual/xstudio.web/)
- XStudio (i.e. http://<ip_address>:8080/xqual/xstudio/)
- the REST API server (i.e. http://<ip_address>:8080/xqual/api?command=getInfo)
and inform all the users that the service is back.



That's it! your server is now updated and all your users can reconnect from their browser using the same URL.