Table of content

Sonar requirements

The 2 minutes tutorial
Upgrade guide
Full installation in 5 steps

Step 1 - Create database
Step 2 - Install server
Step 3 - Configure database
Step 4 - Start server
Step 5 - Configure Maven2
Run as a service
Declare the Sonar Maven Repository inside Nexus
Running Sonar behind a Proxy

Sonar requirements

Sonar is a web application and a maven plugin using both a database. This means that most Sonar users interact with Sonar through web browsers from any computer.

Server side

Sonar runs on any operating system that support Java and Maven. Those two pieces of software need to be installed first :

Java Development Kit v1.5 or later
Maven 2.0.9+, 2.1.+ or 2.2.+

Sonar requires a relational database for storage of measures data. Sonar supports :

MySQL 5.x+
Oracle 10g+
PostgreSQL 8.3+ (8.2 since Sonar 1.12)
MS SQLServer 2005 since Sonar 2.0

Sonar ships pre-configured with the Derby embedded database, which is suitable for evaluation purposes. Although using the Derby database gives access to a fully functional version, we do not test any version migration on it. Therefore, before deploying to a production environment, we strongly recommend that you connect Sonar to an enterprise database.

The Sonar web server requires 500Mo of RAM to run efficiently.
In terms of data space and as an indication, on Nemo the public instance of Sonar, 2Go 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 350 Ko of data space. Nemo is currently running on a Amazon EC2 small instance.

Client side

Sonar works with most modern browsers:

Firefox 2.x and 3.x
Internet Explorer 6.x, 7.x and 8.x
Safari (latest version)
Opera (latest version)
Chrome (latest version)

Note
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 :

bin\windows-x86-32\StartSonar.bat

or on other plateforms :

bin/[OS]/sonar.sh console

Execute the following command on your maven2 projects.

mvn clean install sonar:sonar

Plugin not found
The maven issue MNG-4001 requires to delete the directory org/codehaus/mojo from its local maven repository. Examples of error logs :

The plugin 'org.apache.maven.plugins:maven-sonar-plugin' does not exist or no valid version could be found
POM 'org.codehaus.sonar:sonar-maven-plugin' not found in repository: Unable to download the artifact from any repository

Maven mirrors
Environments with Maven mirrors like Nexus need some extra configuration. Please read the installation guide for more details.

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 paludis:

paludis -i dev-util/sonar-bin

Or using emerge:

emerge -av dev-util/sonar-bin

The only thing left to do is to start Sonar:
```
/etc/init.d/sonar start
```
And, optionally, add it to start at boot:
```
rc-update add sonar default
```
Browse to http://localhost:9000 For administration features, default login/password is admin/admin

Upgrade guide

Before upgrading, please read the notes for versions 2.0 , 2.1 or 2.2.
Stop Sonar :
```
bin/<SYSTEM>/sonar.sh stop
```
Unzip the new version of 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
If you use rules extensions or your own jdbc drivers, copy the corresponding directories into /extensions from {$OLD_SONAR_HOME} to {$NEW_SONAR_HOME}
If you are using Sonar plugins, you should copy them to the new instance. Check the compatibility between Sonar core and the plugin before doing so.
Backup your database
If Sonar is deployed on a JEE application server, repackage the WAR file by executing the script /war/build-war

Start the server (or restart the application server)

bin/<SYSTEM>/sonar.sh start
bin/windows-x86-32/StartSonar.bat on windows

Browse to http://localhost:9000/setup and follow setup instructions.
Re-analyze your projects to get fresh measures

Upgrade process
Upgrade process can take a while depending on the size of projects portfolio. To monitor the process, checks the logs and / or the console.

Migration is completed when an analysis has been run on project. Only at that point will you get new functionality working for sure.

Full installation in 5 steps

Step 1 - Create database

Apache Derby is embedded by default 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. The following are currently supported : MySQL 5.x, Oracle 10g XE, Postgresql and MS SqlServer 2005. It may work on other versions.

Tables and indexes are automatically created when launching for the first time. It is therefore necessary that the user that will access the database has sufficient rights to be able to create, suppress and update objects.

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 is 'sonar')
* sonar.jdbc.password : the password (default is 'sonar')

Example for MySQL :

#sonar.jdbc.url: jdbc:derby://localhost:1527/sonar;create=true
#sonar.jdbc.driver: org.apache.derby.jdbc.ClientDriver
#sonar.jdbc.defaultTransactionIsolation: 1
#sonar.jdbc.validationQuery: values(1)
sonar.jdbc.url: jdbc:mysql://localhost:3306/sonar?useUnicode=true&characterEncoding=utf8
sonar.jdbc.driver: com.mysql.jdbc.Driver
sonar.jdbc.validationQuery: select 1

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 :

sonar.web.host : 192.0.0.1
sonar.web.port: 80
sonar.web.context: /sonar

Execute the following script to start the server :

on linux/mac : bin/[YOUR PLATEFORM]/sonar.sh start
on windows : bin/windows-x86-32/StartSonar.bat

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.

Note
Prior to Sonar 1.9, it was necessary to follow setup instructions. From 1.9 setup is run automatically on a fresh installation when launching the server.

Mode 2 - Deploy on Tomcat application server

Sonar can be packaged as a WAR then deployed into an existing JEE application server. To use this method of installation, you must already know how to deploy a web application on the application server of choice. The only supported JEE application servers are Tomcat 5.x, 6.x and 7.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

A minimum heap size of 512Mo is required.

Prior to Sonar 2.2, the WAR file must be rebuilt each time the configuration is updated (conf/sonar.properties 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/)

To increase memory heap size, set the CATALINA_OPTS variable before starting Tomcat :

CATALINA_OPTS="-Xms1024m -Xmx1024m -Dorg.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true -XX:MaxPermSize=256m"

More details on this blog.

Step 5 - Configure Maven2

Sonar uses a Maven2 plugin to analyze sources and to inject measures into the database. That's why database properties must be defined into the Maven2 configuration. Edit settings.xml file, located into $MAVEN_HOME/conf or ~/.m2, and add the parameters from step 3.

If data collection and server are on different boxes, set the server host with the property 'sonar.host.url'.

Example :

<settings>
    <profiles>
        <profile>
            <id>sonar</id>
            <activation>
                <activeByDefault>true</activeByDefault>
            </activation>
            <properties>
                <!-- EXAMPLE FOR MYSQL -->
                <sonar.jdbc.url>
                  jdbc:mysql://localhost:3306/sonar?useUnicode=true&amp;characterEncoding=utf8
                </sonar.jdbc.url>
                <sonar.jdbc.driver>com.mysql.jdbc.Driver</sonar.jdbc.driver>
                <sonar.jdbc.username>sonar</sonar.jdbc.username>
                <sonar.jdbc.password>sonar</sonar.jdbc.password>

                <!-- SERVER ON A REMOTE HOST -->
                <sonar.host.url>http://myserver:1234</sonar.host.url>
            </properties>
        </profile>
     </profiles>
</settings>

Warning : the property sonar.host.url MUST NOT end with a slash character. Otherwise, JDBC driver is not found by the Sonar Maven plugin. See SONAR-1685.

It is recommended to increase the Java heap memory. It avoids getting OutOfMemoryError failures. Set the MAVEN_OPTS environment variable :

export MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=256m"

Run as a service

MS Windows

Install/uninstall NT service :

bin/windows-x86-32/InstallNTService.bat
bin/windows-x86-32/UninstallNTService.bat

Start/stop the service :

bin/windows-x86-32/StartNTService.bat
bin/windows-x86-32/StopNTService.bat

Linux

The following has been tested on Ubuntu 8.10.

Create the file /etc/init.d/sonar with this content :

#! /bin/sh
/usr/bin/sonar $*

Register Sonar at boot time :

sudo ln -s $SONAR_HOME/bin/linux-x86-32/sonar.sh /usr/bin/sonar
sudo chmod 755 /etc/init.d/sonar
sudo update-rc.d sonar defaults

Declare the Sonar Maven Repository inside Nexus

The Sonar Maven plugin has multiple runtime dependencies on for instance jdbc driver to use, checkstyle or pmd extensions, etc ... To keep Sonar installation simple and avoid Sonar users to manually deploy all those dependencies on their own Maven repository, Sonar server embeds its own repository. This repository can be reached at the following URL : http://yoursonar:sonarport/deploy/maven/README.txt. By default, you don't have to change anything and the Sonar Maven plugin uses the "sonar.host.url" property to know where is located this repository.

If a Maven mirror is defined in your company like the following one :

<settings>
  <mirrors>
    <mirror>
      <id>Nexus</id>
      <name>Your Nexus Public Mirror</name>
      <url>http://nexusServer:nexusPort/nexus/content/groups/public</url>
      <mirrorOf>*</mirrorOf>
    </mirror>
  </mirrors>
</settings>

and you don't want to change this configuration to exclude Sonar Maven Repository from this mirroring mechanism, here is the way you need to configure your Nexus repository manager to declare the Sonar Maven Repository :

1- Add a new repository with the following properties :

Format : Maven2
Repository Policy : Release
Remote Storage Location : http://sonarServer:sonarPort/deploy/maven
Download Remote Indexes : False
Checksum Policy : Ignore

2- Add this newly created repository to your public group of repositories.

3- No more to do except launching the Sonar Maven plugin on a project to check your new configuration.

Note for Nexus 1.6
The auto blocking feature of Nexus 1.6 must be deactivated on the Sonar proxy. This issue is fixed since Sonar 2.1.

Note
The status of this repository inside Nexus will remain "In Service - Checking remote ...". This issue is fixed since Sonar 1.9.

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 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 HTTPd configuration file for the www.somecompany.com virtual host. Include the following to expose Sonar via mod_proxy at http://www.somecompany.com/ :

ProxyRequests Off
ProxyPreserveHost On
<VirtualHost *:80>
  ServerName www.somecompany.com
  ServerAdmin admin@somecompany.com
  ProxyPass / http://sonarhost:sonarport/
  ProxyPassReverse / http://sonarhost:sonarport/
  ErrorLog logs/somecompany/sonar/error.log
  CustomLog logs/somecompany/sonar/access.log common
</VirtualHost>

By default, mod_proxy uses HTTP protocol to communicate with the Sonar instance. For performance concerns, you might prefer using the AJP13 protocol. This protocol is packet-oriented. A binary format is chosen over the more readable plain text for reasons of performance. To cut down on the expensive process of socket creation, the web server will attempt to maintain persistent TCP connections to the servlet container, and to reuse a connection for multiple request/response cycles.

If you want to use this AJP13 protocol you must to activate the mod_proxy_ajp module and then edit the sonar.properties configuration file and uncomment the sonar.ajp13.port property :

# Apache mod_jk connector. Supported only in standalone mode.
# Uncomment to activate AJP13 connector.
# sonar.ajp13.port: 8009

Once this done, edit the HTTPd configuration file for the www.somecompany.com virtual host and make the following changes :

  ProxyPass / ajp://sonarhost:sonarajpport/
  ProxyPassReverse / ajp://sonarhost:sonarajpport/

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, mod_proxy and mod_proxy_ajp, 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/ :

# the server directive is nginx's virtual host directive
server {
  # port to listen on. Can also be set to an IP:PORT
  listen 80;

  # sets the domain[s] that this vhost server requests for
  server_name www.somecompany.com;

  location / {
    proxypass http://sonarhost:sonarport;
  }
}

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.

Shortcuts

Page Operations

Browse Space

Install Sonar

Labels: