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
Oracle JDK	1.5 1.6 1.7 not tested and there is a user, who reported about possible problem - http://markmail.org/message/e22ar72xybvq5zgj
IBM JDK
GCJ
Oracle JRockit
Database
Apache Derby	Bundled with Sonar but supported for evaluation use only. Although using the Derby database gives access to a fully functional version, upgrades are disabled. Therefore, before deploying to a production environment, we strongly recommend that you use an enterprise database.
Microsoft SQL Server	2005 with bundled jTDS 1.2 Express Editions are supported 2008 not supported but successfully tested by end-users Collation must be case-sensitive (CS) and accent-sensitive (AS)
MySQL	5.x with bundled JDBC Connector/J 5.1 6.x with bundled JDBC Connector/J 5.1
Oracle	10G with Oracle 11.2.x drivers 11G with Oracle 11.2.x drivers XE Editions are supported The driver ojdbc14.jar is not supported Only thin is supported, not OCI
PostgreSQL	8.3 8.4 9.0 (from version 2.6 onwards) 9.1 (from version 2.6 onwards)
Application Servers
Jetty 6	Bundled with Sonar
Apache Tomcat	5.5 6.0 7.0 not tested
JBoss
GlassFish
Web Browsers
Microsoft Internet Explorer	IE6 is supported except for management of reviews IE7 IE8 IE9 is fully supported from version 2.12 onwards.
Mozilla Firefox	All versions
Google Chrome	Latest stable version supported Tested with 12
Opera	Not tested
Safari	Latest stable version supported

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.

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.

Install Sonar