SONAR-4898 update documentation and Minimum Viable Environment

8 files changed, 80 insertions, 155 deletions

diff --git a/sonar-application/src/main/assembly/conf/sonar.properties b/sonar-application/src/main/assembly/conf/sonar.properties
index ce2bb92b4cd..578cfa942bd 100644
--- a/sonar-application/src/main/assembly/conf/sonar.properties
+++ b/sonar-application/src/main/assembly/conf/sonar.properties
@@ -1,35 +1,16 @@
-# This file must contain only ISO 8859-1 characters
-# see http://docs.oracle.com/javase/1.5.0/docs/api/java/util/Properties.html#load(java.io.InputStream)
+# This file must contain only ISO 8859-1 characters.
+# See http://docs.oracle.com/javase/1.5.0/docs/api/java/util/Properties.html#load(java.io.InputStream)
 #
-# To use an environment variable, use the following syntax :  ${env:NAME_OF_ENV_VARIABLE}
-# For example:
-#   sonar.jdbc.url= ${env:SONAR_JDBC_URL}
-
-
-#--------------------------------------------------------------------------------------------------
-# TO BE DOCUMENTED - WORK IN PROGRESS
-#sonar.search.javaOpts=-Djava.net.preferIPv4Stack=true -Djava.awt.headless=true -Xmx256m -Xms256m -Xss256k -XX:+UseParNewGC -XX:+UseConcMarkSweepGC -XX:CMSInitiatingOccupancyFraction=75 -XX:+UseCMSInitiatingOccupancyOnly
-#sonar.search.port=9001
-#sonar.search.jmxPort=9002
-
-# For debug only
-#sonar.search.httpPort=
-
-#sonar.web.javaOpts=-server -Xmx768m -XX:MaxPermSize=160m -XX:+HeapDumpOnOutOfMemoryError
-#sonar.web.jmxPort=9003
-
-# Paths are absolute or relative to installation root directory
-#sonar.path.data=data
-#sonar.path.logs=logs
-#sonar.path.temp=temp
+# Property values can:
+# - reference an environment variable, for example sonar.jdbc.url= ${env:SONAR_JDBC_URL}
+# - be encrypted. See http://docs.codehaus.org/display/SONAR/Settings+Encryption
 
 
 #--------------------------------------------------------------------------------------------------
 # DATABASE
 #
-# IMPORTANT: the embedded H2 database is used by default. It is recommended for tests only.
-# Please use a production-ready database. Supported databases are MySQL, Oracle, PostgreSQL
-# and Microsoft SQLServer.
+# IMPORTANT: the embedded H2 database is used by default. It is recommended for tests but not for
+# production use. Supported databases are MySQL, Oracle, PostgreSQL and Microsoft SQLServer.
 
 # User credentials.
 # Permissions to create tables, indices and triggers must be granted to JDBC user.
@@ -37,11 +18,9 @@
 #sonar.jdbc.username=sonar
 #sonar.jdbc.password=sonar
 
-#----- Embedded database H2
-# Note: it does not accept connections from remote hosts, so the
-# SonarQube server and the maven plugin must be executed on the same host.
-
-# Comment the following line to deactivate the default embedded database.
+#----- Embedded database
+# It does not accept connections from remote hosts, so the
+# SonarQube server and the analyzers must be executed on the same host.
 sonar.jdbc.url=jdbc:h2:tcp://localhost:9092/sonar
 
 # directory containing H2 database files. By default it's the /data directory in the SonarQube installation.
@@ -56,24 +35,21 @@ sonar.jdbc.url=jdbc:h2:tcp://localhost:9092/sonar
 
 
 #----- Oracle 10g/11g
-# To connect to Oracle database:
-#
-# - It's recommended to use the latest version of the JDBC driver (ojdbc6.jar).
-#   Download it in http://www.oracle.com/technetwork/database/enterprise-edition/jdbc-112010-090769.html
-# - Copy the driver to the directory extensions/jdbc-driver/oracle/
+# - Only versions 11.2.* of Oracle JDBC driver are supported, even if connecting to lower Oracle versions.
+# - The JDBC driver must be copied into the directory extensions/jdbc-driver/oracle/
 # - If you need to set the schema, please refer to http://jira.codehaus.org/browse/SONAR-5000
 # - Comment the embedded database and uncomment the following line:
 #sonar.jdbc.url=jdbc:oracle:thin:@localhost/XE
 
 
 #----- PostgreSQL 8.x/9.x
-# Comment the embedded database and uncomment the following property to use PostgreSQL.
+# Comment the embedded database and uncomment the following property to connect to PostgreSQL.
 # If you don't use the schema named "public", please refer to http://jira.codehaus.org/browse/SONAR-5000
 #sonar.jdbc.url=jdbc:postgresql://localhost/sonar
 
 
-#----- Microsoft SQLServer
-# The Jtds open source driver is available in extensions/jdbc-driver/mssql. More details on http://jtds.sourceforge.net
+#----- Microsoft SQLServer 2005/2008
+# Only the distributed jTDS driver is supported and must not be changed.
 #sonar.jdbc.url=jdbc:jtds:sqlserver://localhost/sonar;SelectMethod=Cursor
 
 
@@ -90,6 +66,18 @@ sonar.jdbc.timeBetweenEvictionRunsMillis=30000
 #--------------------------------------------------------------------------------------------------
 # WEB SERVER
 
+# Web server is executed in a dedicated Java process. By default its heap size is 768Mb.
+# Use the following property to customize JVM options. Enabling the HotSpot Server VM
+# mode (-server) is recommended.
+# Note that the option -Dfile.encoding=UTF-8 is mandatory.
+#sonar.web.javaOpts=-Xmx768m -XX:MaxPermSize=160m -XX:+HeapDumpOnOutOfMemoryError \
+#  -Djava.awt.headless=true -Dfile.encoding=UTF-8 -Djruby.management.enabled=false
+
+# Web server requires a JMX RMI port to be open. Default is 9003. A free port is
+# dynamically used is value is 0.
+# This JMX port must be private and must not be exposed to the Internet.
+#sonar.web.jmxPort=9003
+
 # Binding IP address. For servers with more than one IP address, this property specifies which
 # address will be used for listening on the specified ports.
 # By default, ports will be used on all IP addresses associated with the server.
@@ -178,15 +166,35 @@ sonar.jdbc.timeBetweenEvictionRunsMillis=30000
 # Access logs are enabled by default.
 #sonar.web.accessLogs.enable=true
 
-# TCP port for incoming AJP connections. Disabled when value is -1.
-# sonar.ajp.port=9009
+# TCP port for incoming AJP connections. Disabled if value is -1. Disabled by default.
+#sonar.ajp.port=-1
+
+
+#--------------------------------------------------------------------------------------------------
+# SEARCH INDEX
+
+# Elasticsearch is used to facilitate fast and accurate information retrieval.
+# It is executed in a dedicated Java process.
+
+# JVM options. Note that enabling the HotSpot Server VM mode (-server) is recommended.
+#sonar.search.javaOpts=-Xmx256m -Xms256m -Xss256k -Djava.net.preferIPv4Stack=true \
+#  -XX:+UseParNewGC -XX:+UseConcMarkSweepGC -XX:CMSInitiatingOccupancyFraction=75 \
+#  -XX:+UseCMSInitiatingOccupancyOnly -XX:+HeapDumpOnOutOfMemoryError \
+#  -Djava.awt.headless=true
+
+# Elasticsearch port. Default is 9001. Use 0 to get a free port.
+# This port must be private and must not be exposed to the Internet.
+#sonar.search.port=9001
 
+# JMX RMI port to monitor Elasticsearch process. Default is 9002. Use 0 to get a free port.
+# It must be private and must not be exposed to the Internet.
+#sonar.search.jmxPort=9002
 
 
 #--------------------------------------------------------------------------------------------------
 # UPDATE CENTER
 
-# The Update Center requires an internet connection to request http://update.sonarsource.org
+# Update Center requires an internet connection to request http://update.sonarsource.org
 # It is enabled by default.
 #sonar.updatecenter.activate=true
 
@@ -207,20 +215,25 @@ sonar.jdbc.timeBetweenEvictionRunsMillis=30000
 
 
 #--------------------------------------------------------------------------------------------------
-# NOTIFICATIONS
-
-# Delay (in seconds) between processing of notification queue
-sonar.notifications.delay=60
+# LOGGING
 
-#--------------------------------------------------------------------------------------------------
-# PROFILING
-# Level of information displayed in the logs: NONE (default), BASIC (functional information) and FULL (functional and technical details)
+# Level of information displayed in the logs: NONE (default), BASIC (functional information)
+# and FULL (functional and technical details)
 #sonar.log.profilingLevel=NONE
 
+# Path to log files. Can be absolute or relative to installation directory.
+# Default is <installation home>/logs
+#sonar.path.logs=logs
+
 
 #--------------------------------------------------------------------------------------------------
-# DEVELOPMENT MODE
-# Only for debugging
+# OTHERS
+
+# Delay in seconds between processing of notification queue. Default is 60 seconds.
+#sonar.notifications.delay=60
 
-# Set to true to apply Ruby on Rails code changes on the fly
-#sonar.rails.dev=false
+# Paths to persistent data files (embedded database and search index) and temporary files.
+# Can be absolute or relative to installation directory.
+# Defaults are respectively <installation home>/data and <installation home>/temp
+#sonar.path.data=data
+#sonar.path.temp=temp
diff --git a/sonar-application/src/main/assembly/lib/jsw/wrapper.conf b/sonar-application/src/main/assembly/lib/jsw/wrapper.conf
index 1020f2003cb..075cd1c5878 100644
--- a/sonar-application/src/main/assembly/lib/jsw/wrapper.conf
+++ b/sonar-application/src/main/assembly/lib/jsw/wrapper.conf
@@ -30,8 +30,6 @@ wrapper.java.library.path.1=./lib
 # Application parameters.  Add parameters as needed starting from 1
 wrapper.app.parameter.1=org.sonar.application.App
 
-# Do not touch the following property. Max memory is set with -Xmx (see above).
-# See https://jira.codehaus.org/browse/SONAR-5204
 wrapper.java.maxmemory=0
 
 #********************************************************************
@@ -41,7 +39,7 @@ wrapper.java.maxmemory=0
 wrapper.console.format=PM
 
 # Log Level for console output.  (See docs for log levels)
-wrapper.console.loglevel=ERROR
+wrapper.console.loglevel=INFO
 
 # Log file to use for wrapper output logging.
 wrapper.logfile=../../logs/application.log
@@ -50,7 +48,7 @@ wrapper.logfile=../../logs/application.log
 wrapper.logfile.format=M
 
 # Log Level for log file output.  (See docs for log levels)
-wrapper.logfile.loglevel=ERROR
+wrapper.logfile.loglevel=INFO
 
 # Maximum size that the log file will be allowed to grow to before
 #  the log is rolled. Size is specified in bytes.  The default value
@@ -104,6 +102,4 @@ wrapper.ntservice.interactive=false
 # Forking Properties
 #********************************************************************
 wrapper.disable_restarts=TRUE
-wrapper.shutdown.timeout=30
-wrapper.jvm_exit.timeout=30
 wrapper.ping.timeout=0
diff --git a/sonar-application/src/main/java/org/sonar/application/App.java b/sonar-application/src/main/java/org/sonar/application/App.java
index dcfa2126811..54642355c3e 100644
--- a/sonar-application/src/main/java/org/sonar/application/App.java
+++ b/sonar-application/src/main/java/org/sonar/application/App.java
@@ -66,7 +66,6 @@ public class App implements ProcessMXBean {
             .setWorkDir(installation.homeDir())
             .setJmxPort(Integer.parseInt(installation.prop(DefaultSettings.WEB_JMX_PORT_KEY)))
             .addJavaOpts(installation.prop(DefaultSettings.WEB_JAVA_OPTS_KEY))
-            .addJavaOpts(DefaultSettings.WEB_JAVA_OPTS_APPENDED_VAL)
             .addJavaOpts(String.format("-Djava.io.tmpdir=%s", installation.tempDir().getAbsolutePath()))
             .addJavaOpts(String.format("-Dsonar.path.logs=%s", installation.logsDir().getAbsolutePath()))
             .setClassName("org.sonar.server.app.WebServer")
diff --git a/sonar-application/src/main/java/org/sonar/application/DefaultSettings.java b/sonar-application/src/main/java/org/sonar/application/DefaultSettings.java
index b4f4485d8c6..d90c8a1bbb0 100644
--- a/sonar-application/src/main/java/org/sonar/application/DefaultSettings.java
+++ b/sonar-application/src/main/java/org/sonar/application/DefaultSettings.java
@@ -49,8 +49,7 @@ class DefaultSettings {
   private static final int WEB_JMX_PORT_DEFVAL = 9003;
 
   static final String WEB_JAVA_OPTS_KEY = "sonar.web.javaOpts";
-  private static final String WEB_JAVA_OPTS_DEFVAL = "-server -Xmx768m -XX:MaxPermSize=160m -XX:+HeapDumpOnOutOfMemoryError";
-  static final String WEB_JAVA_OPTS_APPENDED_VAL = "-Djava.awt.headless=true -Dfile.encoding=UTF-8 -Djruby.management.enabled=false";
+  private static final String WEB_JAVA_OPTS_DEFVAL = "-Xmx768m -XX:MaxPermSize=160m -XX:+HeapDumpOnOutOfMemoryError -Djava.awt.headless=true -Dfile.encoding=UTF-8 -Djruby.management.enabled=false";
 
   static final String JDBC_LOGIN_KEY = "sonar.jdbc.username";
   private static final String JDBC_LOGIN_DEFVAL = "sonar";
diff --git a/sonar-application/src/main/java/org/sonar/application/Installation.java b/sonar-application/src/main/java/org/sonar/application/Installation.java
index a55dc7325d0..eccc7fefd50 100644
--- a/sonar-application/src/main/java/org/sonar/application/Installation.java
+++ b/sonar-application/src/main/java/org/sonar/application/Installation.java
@@ -22,6 +22,7 @@ package org.sonar.application;
 import org.apache.commons.io.FileUtils;
 import org.apache.commons.io.FilenameUtils;
 import org.apache.commons.io.IOUtils;
+import org.sonar.process.MinimumViableEnvironment;
 import org.sonar.process.Props;
 
 import javax.annotation.CheckForNull;
@@ -42,15 +43,15 @@ public class Installation {
     systemProperties.putAll(System.getenv());
     systemProperties.putAll(System.getProperties());
 
-    init(new SystemChecks(), detectHomeDir(), systemProperties);
+    init(new MinimumViableEnvironment(), detectHomeDir(), systemProperties);
   }
 
-  Installation(SystemChecks systemChecks, File homeDir, Properties systemProperties) throws URISyntaxException, IOException {
-    init(systemChecks, homeDir, systemProperties);
+  Installation(MinimumViableEnvironment minimumViableEnvironment, File homeDir, Properties systemProperties) throws URISyntaxException, IOException {
+    init(minimumViableEnvironment, homeDir, systemProperties);
   }
 
-  void init(SystemChecks systemChecks, File homeDir, Properties systemProperties) throws URISyntaxException, IOException {
-    systemChecks.checkJavaVersion();
+  void init(MinimumViableEnvironment minViableEnv, File homeDir, Properties systemProperties) throws URISyntaxException, IOException {
+    minViableEnv.check();
 
     this.homeDir = homeDir;
     props = initProps(homeDir, systemProperties);
@@ -108,11 +109,6 @@ public class Installation {
     File dir = configuredDir(propKey, defaultRelativePath);
     FileUtils.deleteQuietly(dir);
     FileUtils.forceMkdir(dir);
-
-    // verify that temp directory is writable
-    File tempFile = File.createTempFile("check", "tmp", dir);
-    FileUtils.deleteQuietly(tempFile);
-
     return dir;
   }
 
diff --git a/sonar-application/src/main/java/org/sonar/application/SystemChecks.java b/sonar-application/src/main/java/org/sonar/application/SystemChecks.java
deleted file mode 100644
index 7a7bd7b95b1..00000000000
--- a/sonar-application/src/main/java/org/sonar/application/SystemChecks.java
+++ /dev/null
@@ -1,35 +0,0 @@
-/*
- * SonarQube, open source software quality management tool.
- * Copyright (C) 2008-2014 SonarSource
- * mailto:contact AT sonarsource DOT com
- *
- * SonarQube is free software; you can redistribute it and/or
- * modify it under the terms of the GNU Lesser General Public
- * License as published by the Free Software Foundation; either
- * version 3 of the License, or (at your option) any later version.
- *
- * SonarQube is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- * Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this program; if not, write to the Free Software Foundation,
- * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
- */
-package org.sonar.application;
-
-class SystemChecks {
-
-  void checkJavaVersion() {
-    String javaVersion = System.getProperty("java.version");
-    checkJavaVersion(javaVersion);
-  }
-
-  void checkJavaVersion(String javaVersion) {
-    if (javaVersion.startsWith("1.3") || javaVersion.startsWith("1.4") || javaVersion.startsWith("1.5")) {
-      // still better than "java.lang.UnsupportedClassVersionError: Unsupported major.minor version 49.0
-      throw new IllegalStateException("Minimal required Java version if 1.6. Got: " + javaVersion);
-    }
-  }
-}
diff --git a/sonar-application/src/test/java/org/sonar/application/InstallationTest.java b/sonar-application/src/test/java/org/sonar/application/InstallationTest.java
index a2a2373606f..ae8a10ba698 100644
--- a/sonar-application/src/test/java/org/sonar/application/InstallationTest.java
+++ b/sonar-application/src/test/java/org/sonar/application/InstallationTest.java
@@ -25,6 +25,7 @@ import org.junit.Before;
 import org.junit.Rule;
 import org.junit.Test;
 import org.junit.rules.TemporaryFolder;
+import org.sonar.process.MinimumViableEnvironment;
 
 import java.io.File;
 import java.io.IOException;
@@ -56,7 +57,7 @@ public class InstallationTest {
 
     Properties initialProps = new Properties();
     initialProps.setProperty("foo", "bar");
-    Installation installation = new Installation(new SystemChecks(), homeDir, initialProps);
+    Installation installation = new Installation(new MinimumViableEnvironment(), homeDir, initialProps);
     assertThat(installation.logsDir()).isEqualTo(logsDir);
     assertThat(installation.homeDir()).isEqualTo(homeDir);
 
@@ -85,7 +86,7 @@ public class InstallationTest {
 
     File dataDir = new File(homeDir, "data");
     try {
-      new Installation(new SystemChecks(), homeDir, new Properties());
+      new Installation(new MinimumViableEnvironment(), homeDir, new Properties());
       fail();
     } catch (IllegalStateException e) {
       assertThat(e.getMessage()).startsWith("Property 'sonar.path.data' is not valid, directory does not exist: " + dataDir.getAbsolutePath());
@@ -93,7 +94,7 @@ public class InstallationTest {
 
     try {
       FileUtils.touch(dataDir);
-      new Installation(new SystemChecks(), homeDir, new Properties());
+      new Installation(new MinimumViableEnvironment(), homeDir, new Properties());
       fail();
     } catch (IllegalStateException e) {
       assertThat(e.getMessage()).startsWith("Property 'sonar.path.data' is not valid, not a directory: " + dataDir.getAbsolutePath());
@@ -107,7 +108,7 @@ public class InstallationTest {
     FileUtils.forceMkdir(webDir);
     FileUtils.forceMkdir(logsDir);
 
-    Installation installation = new Installation(new SystemChecks(), homeDir, new Properties());
+    Installation installation = new Installation(new MinimumViableEnvironment(), homeDir, new Properties());
     assertThat(installation.prop("sonar.jdbc.username")).isEqualTo("angela");
   }
 }
diff --git a/sonar-application/src/test/java/org/sonar/application/SystemChecksTest.java b/sonar-application/src/test/java/org/sonar/application/SystemChecksTest.java
deleted file mode 100644
index e0c7dd15b5f..00000000000
--- a/sonar-application/src/test/java/org/sonar/application/SystemChecksTest.java
+++ /dev/null
@@ -1,44 +0,0 @@
-/*
- * SonarQube, open source software quality management tool.
- * Copyright (C) 2008-2014 SonarSource
- * mailto:contact AT sonarsource DOT com
- *
- * SonarQube is free software; you can redistribute it and/or
- * modify it under the terms of the GNU Lesser General Public
- * License as published by the Free Software Foundation; either
- * version 3 of the License, or (at your option) any later version.
- *
- * SonarQube is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- * Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this program; if not, write to the Free Software Foundation,
- * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
- */
-package org.sonar.application;
-
-import org.junit.Test;
-
-import static org.fest.assertions.Assertions.assertThat;
-import static org.fest.assertions.Fail.fail;
-
-public class SystemChecksTest {
-
-  @Test
-  public void checkJavaVersion() throws Exception {
-    SystemChecks checks = new SystemChecks();
-
-    // yes, sources are compiled with a supported Java version!
-    checks.checkJavaVersion();
-
-    checks.checkJavaVersion("1.6.1_b2");
-    try {
-      checks.checkJavaVersion("1.5.2");
-      fail();
-    } catch (IllegalStateException e) {
-      assertThat(e).hasMessage("Minimal required Java version if 1.6. Got: 1.5.2");
-    }
-  }
-}