CONTENTS:
--------------------------------------------------------------------------------

0.  ABOUT
1.  REQUIREMENTS
2.  BUILDING THERMOSTAT
3.  RUNNING THERMOSTAT
3.1 PASSING JVM SPECIFIC OPTIONS
3.2 GNOME KEYRING
4.  EXTENDING THERMOSTAT
5.  SYSTEM PROPERTIES
6.  LICENSE
7.  REFERENCES


--------------------------------------------------------------------------------
0. ABOUT

Thermostat is a monitoring, profiling and serviceability tool for Java
applications. It allows users to examine, trace and profile various
attributes of a running JVM (and its environment) to understand how it
is behaving.

Please use the discussion list for any questions, concerns or
comments.

Additional resources:
- Homepage: http://icedtea.classpath.org/thermostat/
- Wiki: http://icedtea.classpath.org/wiki/Thermostat
- Discussion List: http://icedtea.classpath.org/mailman/listinfo/thermostat
- Bug tracker: http://icedtea.classpath.org/bugzilla/


--------------------------------------------------------------------------------
1. REQUIREMENTS

* OpenJDK 7 (or OpenJDK 8)

  Thermostat requires at least Java 7 to build and run. Thermostat has
  been tested with OpenJDK 7 and 8. Other VMs or versions may or may
  not work. Thermostat needs a full JDK to run. It will not work
  correctly with just a JRE.

* Maven (it will download all the java dependencies for you)
* Make, GCC + autoconf
* MongoDB server

  Thermostat requires mongodb (http://www.mongodb.org/) server >= 2.0.0.

  On Fedora, you can obtain it via:

    yum install mongodb-server

* Either a /etc/os-release file or lsb_release
* Gnome Keyring Daemon development libraries plus pkg-configs. Either libsecret
  based or a libgnome-keyring based solution is supported.
* GTK 2+ development libraries plus pkg-configs

  Gnome Keyring/GTK2+ development libraries are required at build time.

  You should check your distribution for the exact name of the libraries, on
  Fedora based distributions you can obtain it via:

    dnf install libsecret-devel gtk2-devel

  or
   
    yum install libgnome-keyring-devel gtk2-devel

  on RHEL/CentOS 6.x via:

    yum install gnome-keyring-devel gtk2-devel

  On Debian (and probably Ubuntu):

    aptitude install libgnome-keyring-dev libgtk2.0-dev

--------------------------------------------------------------------------------
2. BUILDING THERMOSTAT

Thermostat consists of:
  * CLI client
  * Swing GUI client
  * The thermostat agent
  * The web service layer

2.1.
   Run "mvn clean install". All tests should pass and the build should
   succeed. It requires a graphical environment for the ui tests.

   Thermostat also includes a Makefile wrapping the maven build.  In most
   cases, simply running "make" will accomplish the same as "mvn clean
   install".  Please see environment variables near beginning of
   Makefile for some options that can be customized.
   
   You can skip the tests phase by running:
   
   mvn -Dmaven.test.skip=true clean install

   If maven is too chatty, you can try to pass the "-q" option:
   
   mvn -q -Dmaven.test.skip=true clean install
   
2.2.
   The resulting Thermostat system can now be found under the directory
   distribution/target/image.

   Please note that the resulting build is non-relocatable. If you move it to
   some other directory, it will not work. Use the thermostat.home maven
   property to set that at build time:

   mvn -Dthermostat.home=/path/to/install/thermostat

   You will have to move the resulting build to the path manually.
           
--------------------------------------------------------------------------------
3. RUNNING THERMOSTAT

  DISCLAIMER: These are simplified instructions as to how to set up and run
              Thermostat on a local system. For production systems see
              instructions in our user guide (see REFERENCES).

  cd into distribution/target/image directory just created

  On first run, set up thermostat using the interactive script:
  bin/thermostat-setup

  Or, alternatively, for development:
  bin/thermostat-devsetup

  This sets up a mongodb user for the thermostat database. That user will be used
  by the thermostat web application to connect to mongodb. Note that Thermostat
  users and their respective roles will have to get defined via the following
  files:
  etc/thermostat-users.properties (users with password)
  etc/thermostat-roles.properties (role memberships for users)

  thermostat-devsetup is NOT recommended for production use.

  To start the agent and the db:
  bin/thermostat web-storage-service

  To start the gui client:
  bin/thermostat gui

  To start the thermostat shell:
  bin/thermostat shell

  Use the help command in order to find out about all available commands:
  bin/thermostat help

See also the user guide in the REFERENCES section of this document.


3.1. PASSING JVM SPECIFIC OPTIONS TO THERMOSTAT

In some cases, it may be desirable to pass arguments to the virtual machine,
for example to increase memory or change the look and feel for the Swing Client.

Thermostat follows a well established convention to enable this: options that
start with -J are not passed to the thermostat launcher, but instead to the
JVM itself.

For example, this command launches thermostat with the Nimbus Look and Feel,
rather then the default one:

bin/thermostat gui \
    -J-Dswing.defaultlaf=javax.swing.plaf.nimbus.NimbusLookAndFeel


3.2. GNOME KEYRING AND THERMOSTAT

Thermostat includes support to store user credentials in the Gnome Keyring
daemon, if the user wishes.  If this is not available at runtime, no credentials
will be stored.

--------------------------------------------------------------------------------
4. EXTENDING THERMOSTAT

Please see the HACKING file for more development information on thermostat
itself.

If you are writing a plugin for thermostat, the README.api file contains a list
of public/support API of thermostat.

--------------------------------------------------------------------------------
5. SYSTEM PROPERTIES

Although Thermostat by default is configured to behave in the best possible
way, there is a number of system properties that allows tweaking the behaviour
of specific areas of the platform.

Here follows the description for the release
referred by this README. Please, refer to 
[3.1. PASSING JVM SPECIFIC OPTIONS TO THERMOSTAT] for an explanation
on how to pass system properties to Thermostat.

IMPORTANT NOTE: Those properties should be considered internal and
may not be used or available in all the releases. Likewise, defaults may
change at any given time without notice.

* Font Tweaks, Swing GUI only

  skip.system.fonts=<boolean>

By default, Thermostat tries to use the same fonts used by GTK on the
currently running Desktop. When this property is set to false, the process
is skipped.

This property is only valid if the default look and feel is used, otherwise
is ignored.

* Windows Translucency, Swing GUI only

  com.redhat.thermostat.popup.opaque=<boolean>

By default, Thermostat tries to use translucency popup menus to add a
subtle effect to its user interface. The user can request fully opaque
windows to be used instead, by setting this property to false.

Note that not all desktop environment support transparency, so this
property may not have any effect.

  com.redhat.thermostat.popup.transparency=<float>

If transparent windows are used, this property influences the amount of
transparency of the windows. The valid range is 0.0 for fully transparent
and 1.0 for fully opaque, the default value is 0.90.

* Mongo Storage Profiling, Mongo Storage only

  thermostat.storage.mongo.profile=<boolean>

Thermostat has some instrumentation code to perform analysis of the
backend databases. In the case of MongoDB, it is possible to run additional
analysis by using Mongo profiling features. The default is to run MongoDB
without profiling support, to turn profiling on this property should be set
to true. This option has only effect when Thermostat is directly responsible
to start the database backend, is ignored otherwise.

  thermostat.storage.mongo.profile.slowms=<integer>

This property has only effect in conjunction with
"thermostat.storage.mongo.profile=true" and controls the threshold in
milliseconds to decide if a database operation is considered "slow". The
default is 100.

* Queued Storage Thread Pool Size

  com.redhat.thermostat.storage.queue.poolSize=<integer>

The above property is used to override the desired thread pool size. The size is
capped at size 100 (the default if no property is specified). This is because
Linux systems usually enforce a per-user process limit of 1024 (ulimit -u).

The above upper bound can be lifted by setting the following property to true:

  com.redhat.thermostat.storage.queue.unbounded=<boolean>

--------------------------------------------------------------------------------
6. LICENSE

Thermostat itself is licensed under GPLv2 with Classpath Exception. Please see
the LICENSE file for more details about the licenses of Thermostat and other
projects used.

--------------------------------------------------------------------------------
7. REFERENCES

  User Guide:
    http://icedtea.classpath.org/wiki/Thermostat/UserGuide