Thank you for downloading Thermostat.

This document contains the following information useful to compile and run
Thermostat:

1. REQUIREMENTS
2. BUILDING THERMOSTAT
3. RUNNING THERMOSTAT
4. PASSING JVM SPECIFIC OPTIONS
5. GNOME KEYRING


--------------------------------------------------------------------------------
REQUIREMENTS

* OpenJDK7

Thermostat requires at least Java 7 to build and run. Thermostat has been tested
with OpenJDK7. Other VMs or versions may or may not work.

* Maven (it will download all the java dependencies for you)

* MongoDB server

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

* Either a /etc/os-release file or lsb_release

* Gnome Keyring Daemon development libraries, plus pkg-configs and gcc

Gnome Keyring development libraries are required at build time.

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

   yum install libgnome-keyring-devel

on RHEL/Centos 6.x via:

   yum install gnome-keyring-devel

On Debian (and probably Ubuntu):

   aptitude install libgnome-keyring-dev

--------------------------------------------------------------------------------
BUILDING THERMOSTAT

1. Run "mvn clean package". All tests should pass and the build should succeed.
   Requires a graphical environment for the ui tests.
   
   You can skip the tests phase by running:
   
   mvn clean package -Dmaven.test.skip=true

   If maven is too chatty, you can try to pass the -q option too:
   
   mvn -q clean package -Dmaven.test.skip=true
   
2. The resultant Thermostat system can now be found under the directory
   distribution/target.
           
            
--------------------------------------------------------------------------------
RUNNING THERMOSTAT

0. cd into distribution/target directory just created

1. To start the agent and the db:
   bin/thermostat service

2. To start the gui client:
   bin/thermostat gui

3. To start the cli client:
   bin/thermostat [--help]


--------------------------------------------------------------------------------
PASSING JVM SPECIFIC OPTIONS

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


--------------------------------------------------------------------------------
GNOME KEYRING

Thermostat includes experimental support to store user credentials in the
Gnome Keyring daemon, this support is currently limited to passwords only.

Runtime supports for the Keyring is optional and can be disabled via a system
property:

 * -J-Dcom.redhat.thermostat.utils.keyring.provider=com.redhat.thermostat.utils.keyring.MemoryKeyring

The memory keyring stores passwords in memory and not on disk. This means
passwords don't persist across Thermostat sessions. A session is terminated by
exiting the application.

NOTE: thermostat keeps all the passwords in clear text memory during execution,
the keyring is only used to securely store passwords on disk. The passwords are
saved in the user session keychain and available to other applications that
can access the keyring.