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
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:
Then, your update scripts are ok and you can follow the normal instructions below...
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.
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)
- 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)
- Unzip the zip file on the VM
(with WinSCP, right-click on the zip file > Custom Commands > Enter > unzip -o "!")
You may be asked to re-authenticate to execute the command remotely:
- 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)
-
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 theupdate_xstudio.sh
file > Edit and comment the line where the script downloads the package - Line ~14)
-
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/apirest_api.default_username
=<XStudio username>rest_api.default_password
=<encrypted password>
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.