= RSence-2.2.0[http://rsence.org/]

== Introduction

RSence is a different and unique development model and software frameworks designed first-hand for real-time web applications. RSence consists of separate, but tigtly integrated data- and user interface frameworks.

RSence could be classified as a thin server - thick client system.

Applications and submobules are installed as indepenent plugin bundles into the plugins folder of a RSence environment, which in itself is a self-contained bundle. A big part of RSence itself is implemented as shared plugin bundles.

The user interface framework of RSence is implemented in high-level user interface widget classes. The widget classes share a common foundation API and access the browser's native API's using an abstracted event- and element layer, which provides exceptional cross-browser compatibility.

The data framework of RSence is a event-driven system, which synchronized shared values between the client and server. It's like a realtime bidirectional form-submission engine that handles data changes intelligently. On the client, changed values trigger events on user interface widgets. On the server, changed values trigger events on value responder methods of server plugin modules. It doesn't matter if the change originates on client or server, it's all synchronized and propagated automatically.

The server framework is implemented as a high-level, modular data-event-driven system, which handles delegation of tasks impossible to implement using a client-only approach.
Client sessions are selectively connected to other client sessions and legacy back-ends via the server by using the data framework.

The client is written in Javascript and the server is written in Ruby. The client also supports CoffeeScript for custom logic. In many cases, no custom client logic is needed; the user interfaces can be defined in tree-like data models. By default, the models are parsed from YAML files, and other structured data formats are possible, including XML, JSON, databases or any custom logic capable of producing similar objects. The server can connect to custom environments and legacy backends accessible on the server, including software written in other languages.


== Installing RSence
Just run this command in the shell, if you have functioning ruby environment installed. Otherwise, read the {file:INSTALL Install Guide} for full installation instructions.
 gem install rsence


== Initializing a new RSence environment

The +init+ command will create a directory called `env_dir` in this example. It asks a few questions about the environment. Use a path and project name that matches your purposes.
 rsence init /home/me/rsence_projects/env_dir


== Project environment structure

==== The basic structure of a project environment (where `env_dir` is the directory of your project) is:

*dir* :: +env_dir/+ :: The environment directory of your project.
*file* :: +env_dir/conf/config.yaml+ :: The configuration file to load by default. It extends the {file:default_conf default configuration}.
*dir* :: +env_dir/run/+ :: This default directory for runtime files, like the PID file of the running rsence instance.
*dir* :: +env_dir/log/+ :: The default directory for log files. +rsence.stderr+ contains error output of the RSence server daemon and installed plugins, including warnings. +rsence.stdout+ contains the standard output of the RSence server daemon and installed plugins.
*dir* :: +env_dir/db/+ :: The default directory for database files. +ses.db+ is the standard SQLite session database, if enabled.
*dir* :: +env_dir/plugins/+ :: The default directory for installed plugin bundles. A newly initialized environment includes the +welcome+ plugin. Feel free to remove it.
*file* :: +env_dir/VERSION+ :: The version of RSence used to initialize the environment. Reserved for future upgrade usage.
*file* :: +env_dir/README+ :: A README file template. Describes what the `env_dir` is about. Edit it to match your project.

=== Configuration file loading order
The configuration files are loaded and applied in this order:
1.  *rsence_gem_path*/conf/default_conf.yaml
2.  *rsence_gem_path*/conf/local_conf.yaml
3.  /etc/rsence/config.yaml
4.  ~/.rsence/config.yaml
5.  *env_dir*/conf/config.yaml
6.  Any files given using +--conf+ arguments, in order of occurrence.

Use the additional configuration files to match system- or user-specific configurations that are common for all projects.

== Running a project

Each command-line tool command takes a number of options, the +env_dir+ argument defaults to the current working directory, otherwise specify the relative or full path to your project environment.

==== Some common options are:
+-a+:: Automatic updates. RSence reloads automatically changed plugin bundles and client libraries.
+-f+:: Doesn't redirect the standard output into a log file. Useful for development when combined with the +run+ command.
+-d+:: Debug mode. Like +-a+ but much more verbose and doesn't obfuscate client data.

=== Running RSence in foreground
  rsence run [options] [env_dir]

=== Starting the RSence daemon
  rsence start [options] [env_dir]

=== Stopping the RSence daemon
  rsence stop [options] [env_dir]

=== Restarting the RSence daemon
  rsence restart [options] [env_dir]

=== Checking if project is running
  rsence status [options] [env_dir]

=== Example:
  rsence run -af /home/me/projects/hello_world

== RSence command-line tool help

=== Lists all available commands
  rsence help

=== Getting detailed help of a command
  rsence help <command>

=== Example:

  rsence help run


For more detailed installation and usage instructions, read the {file:INSTALL Install Guide} document.

=== The bleeding edge (for developers)
RSence comes in two varieties:
1. rsence : The stable release intended for running in production environments.
2. rsence-pre : The active development snapshot intended for develoment environments. Runtime-wise, it's nearly as stable as the stable version, but features are constantly added and sometimes changed.

To use "rsence-pre", install the "rsence-pre" gem and use the "rsence-pre" instead of "rsence" command-line tool.

=== Licensing and commercial support options
* {file:LICENSE.txt *GPL*} version 3 by default.
* Riassence[http://riassence.com/] Inc. provides commercial support, custom licensing arrangements and various other services.

=== Community support
* http://rsence.org/
* IRC channel +#rsence+ on the FreeNode IRC network

=== Keywords:
HTML5 Javascript CoffeeScript Ruby RIA Server Client Data-Driven Event-Driven Web Framework