Upgrading SonarQube to a newer version

This, as my other SonarQube guides, are meant for developers who are “improvising” system administrators. It is a detailed and comprehensive guide facing real life situations. As the upgrade guide on SonarQube documentation website is not, in my opinion, clear enough, I’ll try to describe the necessary steps in doing the upgrade. Specifically I will perform the upgrade from the SonarQube version 5.6 to SonarQube version 6.0. However this guide may be valid also for different version updates (or at least a part of it).

As I already have upgraded to the LTS version and there are no other LTS version available in my upgrade path, I can proceed with my simple upgrade. If you are not in this situation, please first check if there is an LTS version released in between your version and the one you intend to upgrade to, then first upgrade to the LTS version following this guide, then to your final version of choice. The steps that follow will be pretty much the same for both of the upgrades.

Preparation

Ideally you followed the instructions in my previous post about installing and configuring SonarQube. I will give for granted that SonarQube is replaying on the port 80 and that you do need to get through proxy for what concerns the internet access. If this is not your case, just keep present this information.

Download first the interested version of SonarQube at http://www.sonarqube.org/downloads/.

Extract the contents of the downloaded zip file in the folder of your choice. I usually do have a folder containing multiple version of the software, like shown in the following image:

Now, before going any further it is wise to check if the community reported any issues in regard to the interested versions of software or about any of the plugins.
This is for sure the case for SonarQube 6.0.
It seems that the authentication interface is changed in SonarQube 6.0 in order to phase out some old software components, thus if you were using LDAP plugin, SSO will not work as expected. You can read further about this issue in a separate post of mine, SonarQube LDAP plugin: a love story

If you can live with eventual issues, proceed with the upgrade. Otherwise you will need to wait for another version hoping that your issue is going to be addressed and solved.

Another important thing is to follow the upgrade path. If not you may face different issues with the database upgrade. I saw many posts in which people didn’t followed the upgrade path and they were facing issues reporting problems with database collation etc.
One of most common ones is the following exception:

2016.09.28 18:23:57 ERROR web[o.s.s.d.m.DatabaseMigrator] Fail to execute database migration: org.sonar.db.version.v60.CleanUsurperRootComponents com.microsoft.sqlserver.jdbc.SQLServerException: Cannot resolve the collation conflict between "Latin1_General_CS_AS" and "SQL_Latin1_General_CP1_CS_AS" in the equal to operation.

This is due to the fact that people haven’t followed the upgrade path. In case you are running a version 5.x prior to the 5.6.x, please follow the upgrade path. This may sound confusing and people other jump over it in the SonarQube documentation. Thing is simple, if in between your version and the version you are trying to upgrade, there is an LTS (Long Term Supported) version of software being published, you first need to upgrade to the LTS version (or multiple upgrades in case you are running an really old version of SonarQube) then you will be able to upgrade to your version of choice.

Upgrading

Always backup your database before proceeding with the upgrade!

First and important thing is to start your new version of SonarQube as a separate instance. This is wise so that you can install and upgrade all of the plugins you need before actually upgrading your database and start using the new version.
Now before starting it, let check a couple of things. Open the sonar.properties configuration file that resides in the conf folder (of your new version 6.0). As I have opted for running SonarQube on port 80, I can stick with the default port and no change there will be necessary so that my services do not clash. Still there is one port more that we need to take care of and that is Elasticsearch. Default port for Elasticsearch is 9001 and if we do try to start another instance of SonarQube on the same machine, an error will be thrown.

Unfortunately we would not be able to see clearly what happened only from the error message shown in console. However in the log file you will find a BindTransportException: Failed to bind to [9001].
Because of this, in sonar.properties file find the sonar.search.port=9001 line, which by the way should be commented out. Remove the hash sign to uncomment it and change the port to 9002.
If you are behind the proxy do not forget to add the relevant settings as described in my previous post.
Once you set all up, you are ready to start in parallel the new instance on SonarQube. Open the command prompt and move do bin\windows-x86-64 folder, the launch StartSonar.bat. If all went well the last message you will see in the console will state Process[ce] is up. Now navigate to localhost:9000 and you should be able to see the new instance home page:

As you can see from the message in the bottom of the page, it started by using the embedded database. No worries about that. Log in as administrator with usual admin/admin credentials and move to the Update center. Here now install all of the plugins you are using in your previous version and update the default ones to the latest available version. Once installed, restart it by using the restart it WITHOUT using the restart button. The restart button only works in case you installed it as a service and not if you run it from the console. In this case a CTRL + C in the console window will stop your instance, then start it again in the same way.

If you had other plugins that are installed and are not available in the update center, as it may be for your own custom plugin, install them manually and restart SonarQube to check that they are compatible with the new version. You will find them in extensions\plugins folder. A copy paste will be sufficient.
Once restarted, open the new versions home page again and check that the manually installed plugins are visible and that there are no errors in the log.

Now we are ready to proceed with the real upgrade. Make sure that all of the settings are equal, both in the sonar.properties files and wrapper.conf file. Once done, stop the service of the previous version and remove it. In console, move to the bin\windows-x86-64 folder and run the StopNTService.bat, then UninstallNTService.bat. Now the old instance of SonarQube is not running any more.

You can now install the service of the new version and start it. Move to the bin\windows-x86-64 folder of your 6.0 version and run InstallNTService.bat.

Note: If you were using a specific account to run your service, make sure that it is set correctly again and restart SonarQube. Otherwise you may face issues with the db upgrade.

Once started, on the server navigate to the http://localhost/setup to start the upgrade procedure. In this step, SonarQube will apply the necessary changes to the database. Again, be sure that you have a backup of your database before proceeding.
This is the page you should see:

Click on the upgrade button and wait.

If case everything went well, soon you will be shown the database is up to date page which means that upgrade went well.

Congrats, your upgrade succeeded.
You will now be redirected to the homepage and you can again start using your SonarQube instance.

In case you get to see this

it means that something went wrong. Unfortunately you will not get much from this page, and in order to check what actually went wrong, you will need to dig into the log file.

Considerations

It is always wise to test the upgrade first in a clone of your production environment. As for many other things make sure you DR strategy is in place before upgrading.