Appendix A. Installation and setup
The purpose of this appendix is to get you up and running on the SonarQube platform. We’ll assume that if you’re here, it’s because you’re ready to give SonarQube a try, so we’ll focus on practical advice and skip the persuasive writing.
Before you can get SonarQube up and running, there are a few prerequisites. You’ll need to have Java installed where you want to run SonarQube, at least version 6, as well as a database.
Don’t let the fact that SonarQube bundles-in the H2 database tempt you to skip this step. H2 is included as a courtesy for initial testing only and is not for long-term, production use. If you try to use H2 as your production database, we guarantee you’ll be disappointed—not least because you cannot upgrade a SonarQube database that’s stored in H2. We use MySQL because, much like SonarQube, it’s free and open source; it’s dependable; and if you decide down the road that you want paid support, it’s available. But you can use any one of the supported databases: Oracle, Postgres, SQL Server, and of course MySQL.
Once you’ve checked off the basic requirements, you can move on to installing SonarQube itself. We’ll start by walking you through verifying your Java installation and setting up the SonarQube database, then move on to installing SonarQube itself, and then finish with some advice on upgrades. For the SonarQube installation and upgrade steps, we’ll look at Windows 7 and Ubuntu Linux.
A.1. Preparing for installation
First, let’s deal with the prerequisites: Java and a database. We won’t show you how to install either of these things—that’s what the internet is for—but we can show you how to make sure you’re ready to install SonarQube.
A.1.1. Verifying Java
To verify that Java is installed and ready, go to a command prompt and type the following command:
java –version
Depending on the version of Java you’re using, the response will be something along these lines:
java version "1.7.0_09" Java(TM) SE Runtime Environment (build 1.7.0_09-b04) Java HotSpot(TM) Server VM (build 20.6-b01, mixed mode)
A.1.2. Database setup
Once you’ve installed a database, you need to create the schema and user that SonarQube will need. After these steps, SonarQube will handle all its own database management for you, but you need to get it bootstrapped first. The following instructions assume you’re using MySQL.
Go to a command prompt (Windows 7 users: run cmd.exe to get to the command line), and type the following command:
mysql -u root -p
This command starts a session with the MySQL database. The -u means that the next thing coming up is the user name to log in as. The -p says you want to specify a password. After you press Enter, you’re prompted for it. Enter the database’s root password. You’ll see a MySQL prompt, like so:
mysql>
You’re nearly ready to create the SonarQube user and database, but first you need to pick a password for the SonarQube user you’re about to make. It’s a good idea to use something different than the root password. You don’t want to use sonar as the password, either.
It’s time to set up the SonarQube schema and user. The good folks at SonarSource make this particularly easy by providing the commands you need in a script format. We’ve reproduced it in listing A.1 for your convenience. As you enter these commands, make sure you end each one with a semicolon, and be sure each instance of the sonar user’s password is enclosed in single quotes.
Listing A.1. Schema and user creation
After each line, MySQL should respond like this:
Query OK, 0 rows affected (0.00 sec)
When you get Query OK after the last line, type exit to quit the session. You’ve just created SonarQube’s database, named sonar, and SonarQube’s user, also named sonar. The last three lines give the sonar user permission to do whatever it wants in the sonar database.
Now you’re ready to move on to the installation of SonarQube itself.
A.2. Installing SonarQube
Ideally, you’ll run SonarQube as a service, whatever your platform. That way, it starts back up automatically after a reboot. We prefer running SonarQube standalone, so that’s what we’ll show you how to set up. The exact steps for setting up a service vary by platform, but the download is the same regardless of platform (which is the beauty of Java applications).
The following URL goes to the download page: www.sonarsource.org/downloads/. The versions’ zip files are listed with the newest first—and the newest is always the one you want. The SonarSource folks release fairly frequently (several times a year), and almost every time the new version contains compelling new features. If you’re running Windows 7, skip ahead to section A.2.2 for specific installation instructions. For Ubuntu, continue with the next section.
A.2.1. Ubuntu
The first thing you need to do is decide where to install the SonarQube server. We use /usr/share, and the scripts that follow reflect that. If you prefer a different parent directory, adjust accordingly.
Listing A.2 is an install script. We’ll tell you what you’re about to do and then give you the commands to do it:
1. Expand the SonarQube zip file into /usr/share in a subdirectory named for the zip file, including the version number.
2. Create a symbolic link to your expanded directory, named sonar (without the version number), in /usr/bin.
3. Create a link in /etc/init.d to the service startup script provided with SonarQube. (For this step, you need to know whether you’re running a 32-bit or 64-bit version of the OS.)
4. Register your startup script with the OS.
Listing A.2. Ubuntu SonarQube installation
Once you’ve completed these steps, SonarQube is installed, but you still need to configure it. Skip ahead to section A.2.3 for those steps.
A.2.2. Windows 7
The first thing you need to do is decide where to install the SonarQube server. We typically put it right into the root of whatever drive is chosen, but that’s more a religious decision than a technical one. Whatever you decide, it’s best to create a parent directory named SonarQube and then expand the zip file you downloaded into a subdirectory with the version in the name. This will make life simpler at upgrade time, which comes fairly frequently.
Once you’ve expanded the zip, you can set up SonarQube as a startup service. The good folks at SonarSource have made this easy for you with an installer. Look in the bin directory of the expanded SonarQube zip, and choose the subdirectory that’s correct for your operating system: windows-x86-32 for a 32-bit operating system or windows-x86-64 for a 64-bit version. In the subdirectory, right-click the InstallNTService.bat file and choose Run as Administrator to make SonarQube a startup service on the box.
Depending on how permissions are set up on your machine, you may get an error when you try to run the service setup script. If you do, look in sonar-<version>/logs at sonar.log. You’ll probably see something like this toward the bottom of the file (although not at the very bottom):
Unable to create file in temporary directory, please check existence
of it and permissions:
C:Windowssystem32configsystemprofileAppDataLocalTemp
If so, open Explorer and try to navigate down the cited path. As you drill in, you’ll eventually be told that you don’t have permissions to access the folder you just tried to open and given an option to grant yourself permissions. Accept the option in the dialog, and keep drilling until you get as far down the path as the directories exist (when we tried it, we got the dialog twice). The last directory in the path (Temp) probably isn’t there. Don’t worry about creating it—now that the permissions are taken care of, SonarQube can handle that for you. Try Run as Administrator again on the install script provided with SonarQube, and you should be good to go.
Next you need to make a few configuration changes.
A.2.3. Configuring SonarQube: Windows 7 and Ubuntu
You’re nearly ready to turn on SonarQube. There’s just one more step: telling it where its database is.
Look in SonarQube’s conf directory for the sonar.properties file, and open it in your favorite text editor. (If you’re on Linux, you’ll need to use sudo to open the file; because you used sudo to unzip the archive originally, root owns all the files.) You’ll find that it’s well documented internally, with clearly named properties and helpful comment blocks above each section. In case you’re not used to the conventions used here, lines that start with a pound sign (#) are comments (or commented-out properties).
There are two formats for properties in this file: one where the key and the value are separated by a colon and whitespace doesn’t seem to matter, and ones where the key and value are separated by an equal sign. Whitespace does matter for these, so don’t insert any spaces around an equal sign, like so:
These two formats aren’t interchangeable, so properties you see with colons initially should retain those colons.
To point SonarQube to the database you set up for it, start by looking for the line that begins with sonar.jdbc.password. The default value is sonar. Change it to the password you set up for the sonar database user earlier:
sonar.jdbc.password: <password you picked>
Next, look for these two lines:
# Comment the following line to deactivate the default embedded database. sonar.jdbc.url: jdbc:h2:tcp://localhost:9092/sonar
Comment-out the second one by adding a pound sign to the beginning of the line.
Scroll down a little until you see this set of lines, and uncomment each one that starts with sonar.jdbc by removing the pound sign from the beginning of the line:
#----- MySQL 5.x/6.x # Comment the embedded database and uncomment the following line to use MySQL #sonar.jdbc.url: jdbc:mysql://localhost:3306/sonar?useUnicode=true&characterEncoding= utf8&rewriteBatchedStatements=true # Optional properties #sonar.jdbc.driverClassName: com.mysql.jdbc.Driver
Be sure to correct the server name in the database access URL if it’s not on the same box as SonarQube. At this point, you could save the file and turn on SonarQube if you wanted, but there are a few other configurations you might like to look at.
If you’re behind a proxy, be sure to uncomment and configure your authentication properties in the Update Center section so you can use SonarQube’s built-in plug-in installation and updating features:
#---------------------------------------------------------
# UPDATE CENTER
#---------------------------------------------------------
# The Update Center requires an internet connection to request http://
update.sonarsource.org
# It is activated by default:
#sonar.updatecenter.activate=true
# HTTP proxy (default none)
#http.proxyHost=
#http.proxyPort=
# NT domain name if NTLM proxy is used
#http.auth.ntlm.domain=
# SOCKS proxy (default none)
#socksProxyHost=
#socksProxyPort=
# proxy authentication. The 2 following properties are used for HTTP and
SOCKS proxies.
#http.proxyUser=
#http.proxyPassword=
Once you’ve finished your configurations, you’re ready to start SonarQube.
A.2.4. Turning it on
It’s time to start the SonarQube service. If you’re not familiar with how to start a service on your platform, we’ll tell you how.
This first time, it will take SonarQube a few minutes to start up—in addition to all the normal startup activities, it’s also creating the tables and indexes it needs in the database. After a few minutes, you should be able to point your browser to http://localhost:9000 and see something like what’s shown in figure A.1.
Windows 7
You can start the service from the Services control panel (which you may have to Run as Administrator); or, if you prefer a command-line interface, open a privileged session by clicking the Start button and typing cmd without pressing Enter. This time, press Shift-Ctrl-Enter. You’re asked if you want to “allow the program to make changes to this computer.” Accept, and at the command line, type
sc start sonar
SonarQube should start. But depending on how permissions are set up on your machine, you may get an error when you try to start SonarQube for the first time. If that’s the case, refer to section A.2.2.
Ubuntu
Enter the following in a terminal:
sudo service sonar start
Figure A.1. Congratulations! SonarQube is up and running.
A.2.5. Default admin account
The final thing you need at this point is the credentials for the default admin account. You need these if you want to make any changes to SonarQube’s default setup. You probably could have guessed, but the login is admin and the password is also admin.
Go ahead and log in now—use the link at upper right in the interface—to change the password. Once you’re logged in, click the username at upper right (Administrator, in this case), and choose My Profile to open the password-change form.
A.3. Upgrading
You’ve just gotten SonarQube installed and up and running. Now seems terribly premature to talk about upgrades. But the SonarSource folks release fairly frequently—as often as eight times a year. And almost every release has compelling new functionality. So when new versions come out, you’ll probably want to upgrade. Go to http://mng.bz/ahZm to sign up to be notified when new versions are available.
The steps for upgrading aren’t onerous:
1. Read the upgrade guide, and download the new version. Expand the zip file into a new directory.
2. Copy your plugins (if any) to the new version.
3. Copy your configuration to the new version.
4. Stop SonarQube.
5. Back up your database.
6. Update your links, aliases, and service to point to the new version.
7. Start SonarQube.
8. Point a browser to http://[yourSonarHost]:9000/setup, and click the button.
As you can see, the steps themselves aren’t difficult, but the list is a little long, and stepping through it can be tedious. Because laziness and impatience are among the chief virtues of a programmer (thank you, Larry Walls!) we’ve scripted the steps in an upgrade. Not only will these steps save you tedium and time, but they ensure consistency of process as well.
You’ll still have to do a few things manually. Of course, you’ll need to perform the download manually—the link is different every time. You should also consult the upgrade guide (it’s linked from the email announcing a new version) in case there are any configuration tweaks you need to make for forward compatibility. After those two steps, though, the rest should be pretty painless. Continue to the next section for the Ubuntu version or to section A.3.2 for Windows 7.
A.3.1. Ubuntu
The Linux upgrade script relies on your having followed our installation guidelines. If you didn’t, then this script won’t work for you. Feel free to use it as a guide for writing your own upgrade script, but don’t run it as-is.
If you did follow our advice, then put the script in listing A.3 into a clearly named file (say, sonarUpgrade.sh) in the same directory as the zip file of the new version, and make it executable (chmod 755 sonarUpgrade.sh).
It’s ready to go, but you have to pass it two arguments: the version number you’re upgrading from and the version number you’re upgrading to.
Kicking it off looks something like this:
./sonarUpgrade.sh 3.4 3.5
If the script is able to verify that you have the 3.5 zip file waiting (or already expanded in the correct location) and that an install of 3.4 exists, it will start the upgrade. You’re asked to enter two different passwords. The first is your sudo password. The script uses the sudo access of the person who invoked it to create directories in privileged locations, to move files around, and to stop and restart the SonarQube service.
The second password is the MySQL root password. That access is used to make a backup copy of your database, which is compressed (with gzip) and placed in the directory of the version you’re upgrading from—the version it went with. If worse comes to worst (not that it should), you’ll be able to restore SonarQube to the instant at which you started the upgrade.
When the script is finished, it instructs you to point a browser at http://[yourSonarHost]:9000/setup and follow the instructions on the screen. That screen presents a button. When you click it, SonarQube kicks off the database structure changes that accompany most upgrades. Depending on the size of your database, these can take a few minutes. When those changes are done, your browser will automatically refresh to SonarQube’s front page. Here’s the script.
Listing A.3. Ubuntu upgrade script
#!/bin/bash
old=$1
oldDir=/usr/share/sonar-${old}
new=$2
newDir=/usr/share/sonar-${new}
if [[ -z $old || -z $new ]]
then
echo "usage: ${0} oldVer newVer"
echo "E.g ${0} 2.9 2.10"
else
if [[ ! -e $oldDir ]]
then
echo "Cannot upgrade from ${old}. Directory does not exist: ${oldDir}"
exit
else
echo "Upgrade from sonar-${old} to sonar-${new}"
if [[ ! -e "sonar-${new}.zip" ]]
then
echo "sonar-${new}.zip not found. Skipping expansion"
else
if [ ! -e /usr/share/sonar-${new} ]
then
echo "expanding sonar-${new}.zip to /usr/share"
sudo unzip -d /usr/share sonar-${new}.zip
echo "copying plugins"
sudo cp $oldDir/extensions/plugins/*.jar $newDir/extensions/plugins/.
echo "copying conf"
sudo mv $newDir/conf/sonar.properties $newDir/conf/
sonar.properties.bak
sudo cp $oldDir/conf/sonar.properties $newDir/conf/.
fi
fi
if [[ ! -e ${newDir} ]]
then
echo "Cannot complete upgrade. Directory for new version does not exist: ${newDir}"
else
echo "Stopping service"
sudo service sonar stop
echo "Updating symlink in /usr/bin"
sudo rm /usr/bin/sonar
sudo ln -s ${newDir} /usr/bin/sonar
echo "Backing up database"
d=`date +"%y%m%d"`
mysqldump -u root -p sonar | gzip -9 > sonar-db-ver${old}-${d}.sql.gz
sudo mv sonar-db-ver${old}-${d}.sql.gz ${oldDir}/.
echo "Starting service"
sudo service sonar start
echo ""
echo "To complete upgrade, access the following in a browser and follow
instructions:"
echo "http://$(hostname):9000/setup"
echo "Once the front page renders, run a trial anaysis"
fi
fi
fi
A.3.2. Windows 7
The Windows upgrade script relies on your having followed our installation guidelines earlier. If you didn’t, then this script won’t work for you. Feel free to use it as a guide for writing your own upgrade script, but don’t run it as-is.
If you did follow our advice, then put the script in listing A.4 into a clearly named file with a .bat extension under the SonarQube root directory, say sonarUpgrade.bat. When you’re ready to use it, download the new version and unzip it into a subdirectory of the SonarQube root named sonar-<version>. Your directory listing should look something like this:
Now you’re ready to kick off the upgrade script, but you can’t just double-click it. You need to pass it two arguments: the version number you’re upgrading from and the version number you’re upgrading to.
To do so, open a privileged command-line session by clicking the Start button, typing cmd, and then pressing Shift-Ctrl-Enter. You’re asked if you “want to allow the following program to make changes to this computer.” Say Yes. At the command line, cd to your SonarQube root directory and then start the script:
cd C:Sonar sonarUpgrade 3.4 3.5
If the script is able to verify that the directories exist for the old and new versions, it starts the upgrade. Part way through, you’re asked to enter the MySQL root password. That access is used to make a backup copy of your database, which is placed in the directory of the version you’re upgrading from—the version it went with. If worse comes to worst (not that it should), you’ll be able to restore SonarQube to the instant at which you started the upgrade.
When the script is finished, it instructs you to point a browser at http://[yourSonarHost]:9000/setup and follow the instructions on the screen. That screen presents a button. When you click it, SonarQube kicks off the database structure changes that accompany most upgrades. Depending on the size of your database, these can take a few minutes. When those changes are done, your browser will automatically refresh to SonarQube’s front page.
You may need to make one small adjustment to the script; it assumes you’re running 64-bit Windows. If you’re using 32-bit instead, then look for this line about halfway down the script:
call %new%inwindows-x86-64InstallNTService
And change the 64 to a 32, like so:
call %new%inwindows-x86-32InstallNTService
Here’s the script.
Listing A.4. Windows upgrade script
@echo off
if "%1"=="" goto :USAGE
if "%2"=="" goto :USAGE
set old=sonar-%1
set new=sonar-%2
if not exist %old% goto :1NOTEXIST
if not exist %new% goto :2NOTEXIST
echo Upgrade from %old% to %new%
echo.
echo Copying conf
move %new%confsonar.properties %new%confsonar.properties.bak
copy %old%confsonar.properties %new%conf /Y
echo Copying plugins
copy %old%extensionsplugins*.jar %new%extensionsplugins /Y
echo.
echo Stopping service
sc stop sonar
sc delete sonar
echo.
echo Backing up database
set date=%date:~4,2%%date:~7,2%%date:~10,4%
set outfile=%old%sonar-db-ver%1-%date%.sql
mysqldump -u root -p sonar > %outfile%
echo.
echo Starting service
call %new%inwindows-x86-64InstallNTService
sc start sonar
echo.
echo To complete upgrade, access the following in a browser and follow
instructions:
echo http://%hostname:9000/setup
goto :DONE
:2NOTEXIST
echo Cannot upgrade to %2. Directory does not exist
goto :DONE
:1NOTEXIST
echo Cannot upgrade from %1. Directory does not exist
goto :DONE
:USAGE
echo "Usage: %0 oldVersion newVersion"
:DONE