| Table of content |
Requirements
Sonar is a web application and a runner (Maven, Ant or Java standalone runner) using both a database. This means that most Sonar users interact with Sonar through web browsers from any computer.
Supported Platforms
Java |
|
|---|---|
| |
IBM JDK |
|
GCJ |
|
| Oracle JRockit | |
Database |
|
Apache Derby |
|
| |
| |
| |
| |
Application Servers |
|
Jetty 6 |
|
| |
| JBoss | |
| GlassFish | |
Web Browsers |
|
Microsoft Internet Explorer |
|
Mozilla Firefox |
|
Google Chrome |
|
Opera |
|
Safari |
|
Notes :
- The Sonar web server requires at least 500Mb of RAM to run efficiently.
- In terms of data space and as an indication, on Nemo the public instance of Sonar, 4Go of data space are used to analyze more than 6 million LOC with an history of 2 years. For every 1'000 LOC to analyze the database stores 600 Ko of data space. Nemo is currently running on a Amazon EC2 small instance.
- To get the full experience Sonar has to offer, you should enable Javascript in your browser.
Technical architecture

The 2 minutes tutorial
It's really simple :
- Download and unzip the distribution

Do not install the application in a directory starting with a digit.
- Execute on Windows :
or on other plateforms :
- Execute the following commands on your Maven projects :
| In case of "Plugin not found" see the FAQ. |
| In case of "Error resolving version for 'org.codehaus.mojo:sonar-maven-plugin': Plugin requires Maven version 3.0" see the FAQ. |
- Browse to http://localhost:9000
- For administration features, default login/password is admin/admin.
The 1 minute installation on Gentoo Linux
It's really simple :
- Configure "Godin's Gentoo Repository" as described on this page : http://code.google.com/p/godin-gentoo-repository/wiki/HowTo
- If you use cave:
Or using emerge:
- The only thing left to do is to start Sonar:
- And, optionally, add it to start at boot:
- Browse to http://localhost:9000 For administration features, default login/password is admin/admin
How to upgrade
This guide describes how to upgrade from one version of Sonar to a later version.
- Check compatibility of installed plugins
- If Sonar is not connected to Internet, check for minimum required versions listed in this page.
- If Sonar is connected to Internet, Update Center lists all the plugins to upgrade or to uninstall :

- Read notes bellow for each version
- Stop Sonar :
- Download and unzip Sonar in a fresh directory, let's say {$NEW_SONAR_HOME}
- Copy sonar.properties and wrapper.conf files from {$OLD_SONAR_HOME}/conf to {$NEW_SONAR_HOME}/conf or configure sonar.properties
- Copy the directories extensions/plugins and extensions/rules from {$OLD_SONAR_HOME} to {$NEW_SONAR_HOME} (if you see problems while starting, try to remove the copied plugins from the extensions/plugins-directory and reinstall the plugins manually via the webinterface)
- If a custom JDBC driver is used, copy it into {$NEW_SONAR_HOME}/extensions/jdbc-driver/<dialect>
- Doing a database backup is recommended
- If Sonar is deployed on a JEE server, build the WAR file by executing the script {$NEW_SONAR_HOME}/war/build-war
- Start server (or deploy war into JEE server) :
- Browse to http://localhost:9000/setup and follow setup instructions
- Analyze your projects to get fresh measures
|
Upgrading can take a while depending on the size of projects portfolio. To monitor the process, check the logs and the console. Upgrade is completed when an analysis has been run on project. Only at that point will you get new functionality working for sure. |
Release Upgrade Notes
Usually Sonar releases come with some specific recommendations for upgrading from the previous version. You have to read the upgrade notes for all versions between your current version and the target version.
- Release 2.0 Upgrade Notes
- Release 2.1 Upgrade Notes
- Release 2.2 Upgrade Notes
- Release 2.3 Upgrade Notes
- Release 2.4 Upgrade Notes
- Release 2.5 Upgrade Notes
- Release 2.6 Upgrade Notes
- Release 2.7 Upgrade Notes
- Release 2.8 Upgrade Notes
- Release 2.9 Upgrade Notes
- Release 2.10 Upgrade Notes
- Release 2.11 Upgrade Notes
- Release 2.12 Upgrade Notes
- Release 2.13 Upgrade Notes
Installation in 4 steps
Step 1 - Create database
Apache Derby is shipped with Sonar. It does not need any installation. It's great for demos and tests but we advice you to use a robust database for real use. See the supported platforms for more information.
To use one of the external databases, it is necessary to explicitly set up the initial database schema and permissions. Tables and indexes will then be automatically created when launching Sonar for the first time. Example scripts for setting MySQL up can be found in extras/database/mysql.
| Character Set When creating a database, the recommended character set is UTF-8. |
| Collation Collation must be case-sensitive. It must also be accent-sensitive in Microsoft SQL Server. |
Step 2 - Install server
Download and unzip the distribution.
Step 3 - Configure database
If you do not use the default embedded database, edit conf/sonar.properties to configure the database access. Templates are available for every supported database. Just uncomment them and comment the first four lines dedicated to derby.
- sonar.jdbc.url : the URL of the database
- sonar.jdbc.driver : the class of the driver
- sonar.jdbc.user : the username (default value is 'sonar')
- sonar.jdbc.password : the password (default value is 'sonar')
Example for MySQL :
For Oracle, copy the JDBC driver to /extensions/jdbc-driver/[YOUR DATABASE]/. Other drivers for supported database are already provided.
Step 4 - Start server
Mode 1 - Start the standalone application
The default listen port is 9000, the default context path is / and Sonar listens by default to all network interfaces : '0.0.0.0'. Once launched, the Sonar web server is available on http://localhost:9000. Parameters can be changed into the file conf/sonar.properties. Here is an example to listen to http://localhost:80/sonar :
Execute the following script to start the server :
- On Linux/Mac OS : bin/<YOUR OS>/sonar.sh start
- On MS Windows : bin/windows-x86-32/StartSonar.bat
- Read "Install on AIX, HPUX or Solaris" for other platforms
Note that you can also run as a NT service with bin/windows-x86-32/InstallNTService.bat then bin/windows-x86-32/StartNTService.bat
You can now browse to http://localhost:9000.
Mode 2 - Deploy on JEE Server
Sonar can be packaged as a WAR then deployed into an existing JEE server. To use this method of installation, you must already know how to deploy a web application on the application server of choice. The supported servers are Tomcat 5.x, 6.x, 7.x and Jetty 6.x.
Installation steps are :
- Edit conf/sonar.properties as described in standalone mode. The file conf/wrapper.conf is never used when deploying to application server.
- Execute the script build-war.sh (or build-war.bat on MS Windows) from the directory war/
- Deploy war/sonar.war to the application server
- Browse to http://localhost/sonar and follow setup instructions
| You can inject environment variables in the "sonar.properties" file You have a specific syntax for that. For instance, to inject the JDBC connection string: This can be quite valuable to better handle production environments. |
A minimum heap size of 512Mb is required. To increase memory heap size on Tomcat, set the CATALINA_OPTS variable before starting Tomcat |
Prior to Sonar 2.2, the WAR file must be rebuilt each time the configuration is updated (new plugins or new extensions).
From Sonar 2.2 onwards, the WAR file is now linked to the Sonar directory (the directory where the distribution is unzipped). It implies that :
- the directory where the distribution is unzipped cannot be removed
- there is no need to rebuild the WAR when installing/uninstalling plugins or rule extensions
- the WAR file must be deployed on the host which contains the Sonar directory
- the WAR file must be rebuilt when the Sonar directory is moved
the WAR file must be rebuilt when a configuration file is updated (directory conf/)

The user who runs Tomcat must have read & write access to Sonar home directory (to allow plugin install from the Web admin console for instance).
More details on this blog.
Mode 3 - Run as a service on MS Windows
Install/uninstall NT service (may have to run these batch files via "Run As Administrator"):
Start/stop the service :
Mode 4 - Run as a service on Linux
The following has been tested on Ubuntu 8.10.
Create the file /etc/init.d/sonar with this content :
Register Sonar at boot time :
Running Sonar behind a Proxy
This section helps you configure Sonar if you want to run Sonar behind a proxy. This can be done for security concerns or to consolidate multiple disparate applications.
Running Sonar behind an Apache Proxy
We assume that you've already installed Apache 2 with module mod_proxy, that Sonar is running and available on http://privates_sonar_host:sonar_port/ and that you want to configure a Virtual Host for www.public_sonar.com.
At this point, edit the HTTPd configuration file for the www.public_sonar.com virtual host. Include the following to expose Sonar via mod_proxy at http://www.public_sonar.com/ :
If the url of the Sonar server must have a context like http://www.public_sonar.com/sonar_context, in that case the following line must be uncommented in the sonar.properties configuration file to prevent using the Apache mod_rewrite :
And of course, the definition of the Apache virtual server must also be slightly updated :
Apache configuration is going to vary based on your own application's requirements and the way you intend to expose Sonar to the outside world. If you need more details about Apache HTTPd and mod_proxy, please see http://httpd.apache.org.
Running Sonar behind Nginx
We assume that you've already installed Nginx, that you are using a Virtual Host for www.somecompany.com and that Sonar is running and available on http://sonahost:sonarport/.
At this point, edit the Nginx configuration file. Include the following to expose Sonar at http://www.somecompany.com/ :
Nginx configuration is going to vary based on your own application's requirements and the way you intend to expose Sonar to the outside world. If you need more details about Nginx, please see http://nginx.org.
Analyse a project
Once installation of Sonar is complete, you can kick off analysis on projects. There are several ways Sonar analysis can be performed :
- using the Maven Plugin
- using the Ant Task
- using the Java Runner
- using a CI engine
It is also possible to inject data manually at any time from the Sonar UI.
A series of advanced parameters is available when running analysis.
