_______             _            
                    / _____ \           | |           
 _ __ ___ _ __ ___ | |     | | ___ _   _| | __ _ _ __ 
| '__/ _ \ '_ ` _ \| |     | |/ __| | | | |/ _` | '__|
| | |  __/ | | | | | |_____| | (__| |_| | | (_| | |   
|_|  \___|_| |_| |_|\_______/ \___|\__,_|_|\__,_|_|   
......................................................
remOcular -  your eyes in the cloud
::::::::::::::::::::::::::::::::::::::::::::::::::::::

Author:  Tobi Oetiker <tobi@oetiker.ch>
Version: #VERSION#, #DATE#

 http://www.remocular.org

remOcular provides a AJAX web interface to Unix command line tools like
traceroute, top, mpstat, ...  The tools are integrated via a plug-in
interface.  remOcular comes with plugins for

 * top - process list
 * mpstat - processors related statistics
 * traceroute - packets trace to network host
 * df - disk free

 ... and many more

remOcular can be easily enhanced to support additional tools.  All it takes
is a plugin module (written in perl) on the server side.

See http://www.remocular.org for more information

INSTALLATION from tar file
--------------------------

Use the regular

 ./configure --prefix=$INSTALL_DIR
 make
 make install

aproach. The configure script will check if the reuqired perl modules are
installed. If they are missing, it will tell you how to install them using a
line like this:

 ./setup/build-perl-modules.sh $INSTALL_DIR/thirdparty

Now try running configure again, it should be happy now.

The installer can be run as a normal user as long as it can write
into the installation directoreis.


CONFIGURATION
-------------
In the PREFIX/etc directory you find a configuration skeleton. Adjust it to
your needs.

RUNNING
-------

You can run remOcular standalone:

  PREFIX/bin/remocular.pl daemon

When running from Apache, it is best to use the FastCGI mode of remocular.

Use remocular.fcgi.dist in PREFIX/htdocs as a template to create your script.

For security reasons it is best to configure your apache to run with suexec.

Sample virtual host config:

  <VirtualHost *:443>
  # suexec will only work for directory underneath
  # /var/www or wherever else your apache copy has its default
  # document root

  DocumentRoot /var/www/remocular

  SuexecUserGroup extopus extopus
  AddHandler fcgid-script .fcgi

  RewriteEngine On
  RewriteBase /var/www/remocular
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteRule (.*) remocular.fcgi/$1 [L]

  </VirtualHost>

INSTALLING from Git
-------------------

* run ./autogetn.sh to create the configure script

* get a copy of the qooxdoo sdk from www.qooxdoo.org

* configure with --with-qooxdoo-sdk=path-to-sdk

DEVELOPEMENT
------------

remOcular is written in Perl using Sebastian Riedels excellent Mojolicious
framework. See http://www.mojolicious.org for more information.

The GUI is written in pure javascript using the qooxdoo toolkit.  
See http://www.qooxdoo.org for more information.

If you want to start hacking the gui, get a copy of the qooxdoo-sdk from
www.qooxdoo.org and specify its location when running configure:

 ./configure --with-qooxdoo-path=/opt/qooxdoo-1.5-sdk

And you may want to get a copy of the required perl modules into place by
running

 ./setup/build-perl-modules.sh backend/thirdparty

To build the source version of remOcular frontend, run

 cd frontend
 make source

And then access it via the built in webserver:

 cd backend/bin
 env QX_SRC_MODE=1 MOJO_LOG_LEVEL=debug REMOCULAR_CONF=../etc/remocular.cfg.dist ./remocular.pl daemon 

It might also be a good idea to fork remocular github and work within
your copy, so that you can easily feed back your changes to the master
version.

If you want to enhance remOcular with additional plugins, you only have to
change the server side.  No JavaScript/Qooxdoo programming is required.  See
the existing plugins for inspiration and add the new plugin to the
remocular.cfg file.  There is also a plugin testing tool in the bin
directory to help you test plugins without going through the webserver.

The Git repo is on https://github.com/oetiker/remOcular

Tobi Oetiker <tobi@oetiker.ch>