= Install Guide

If you already have a working ruby environment and know what to do, the easiest way is just:

 gem install rsence

If you have an older version of rsence installed, it's be automatically
updated along other gems when you run:

 gem update

For system-wide installs, run the gem command as a superuser. A common way
for doing so is prefixing the command with sudo.

RSence 2.1 is verified to be compatible with Rubinius. To use RSence with
Rubinius, just use "rbx gem" instead of just "gem" for installation.

The following instructions contain detailed steps for installing Ruby, RSence
and its dependencies on each supported platform:


== System Dependencies

This is a list of system level dependencies. You only need to do this step once; follow the steps of for your target operating system.

=== Mac OS X

==== Mac OS X 10.6

* Install *XCode*[http://developer.apple.com/mac/] to get the essential development tools, like compilers.
* Proceed to section 3.0

==== Mac OS X 10.4 and 10.5

This step applies only to Mac OS X 10.4 "Tiger" and 10.5 "Leopard". The default ruby build of these versions of Mac OS X is somewhat broken.

* Install *XCode*[http://developer.apple.com/mac/] to get the essential development tools, like compilers.
* Install *MacPorts*[http://www.macports.org/]
* Install the ruby and rb-rubygems packages using Terminal like this:
    sudo port install ruby
    sudo port install rb-rubygems
* Proceed to section 3.0

=== Debian and Ubuntu Linux

This step applies only to Debian, Ubuntu and similar Linux distributions.

* Install these packages:
    sudo apt-get install build-essential ruby-full rubygems rake
* Proceed to section 3.0

=== Microsoft Windows

RSence works just fine on Windows too, with a few limitations.
Windows compatibility has been officially tested on Windows XP SP3 and Windows 7 (64 bit).

==== Install ruby 1.8.7:
* Download Ruby 1.8.7-p302 from http://rubyinstaller.org/downloads
* Run the downloaded exe to install ruby
  * In the installation and destination prompt, check these options:
    * Add Ruby executables to your PATH
    * Associate .rb and .rbw files with this Ruby installation
* Download and Install the Development Kit (DevKit-tdm-...-sfx.exe) from http://rubyinstaller.org/downloads
  * Extract the included directories into the directory where you installed ruby, which is +C:\ruby+ by default.

==== Install RSence
* In the command prompt, run:
    gem update --system
    gem install rsence
    rsence help

==== Create RSence environment

Replace the +\my_projects+ path with the path to the directory where you want to run or develop your projects. Likewise, replace +my_project+ with something descriptive for your project.

* In the command prompt, run:
    cd \my_projects
    rsence init my_project
* Answer the questions
* In the command prompt, run:
    rsence run my_project
* Open your web browser in the address as configured.
  * If the address is +0.0.0.0+, enter +127.0.0.1+ instead.
  * Using just defaults, the following URL should work: http://127.0.0.1:8001

==== Windows limitations
If you install the sqlite dll and the sqlite3-ruby gem, you'll gain persistent sessions and this warning message will disappear:
`Warning: Session database is not available. Can't use persistent sessions`

It's not a dependency in the default install, because it's not strictly required and makes the first installation much easier. Also, you can use any other database supported by Sequel instead of Sqlite.

Backgrounding on Windows is not yet implemented, because POSIX signals are not fully implemented in windows and backgrounding requires some Windows-specific service hooks.

However, if you run RSence under Cygwin, everything should work like on a UNIX machines.


=== Other UNIX / Linux systems:

This step applies to systems not listed above.

You'll have to figure out how to install the dependencies on your own, but generally this is the list of software you should look for:

* Ruby
  * Version 1.8.7 or newer
  * http://ruby-lang.org
* RubyGems
  * Ruby package manager
* A standard set of compilers and build tools to build the gems with C extensions.
  * gcc, make etc.


== Ruby Library Dependencies

The `rsence` gem depends on the dummy `rsence-deps` gem, which depends on all essential dependencies of RSence.
Optionally, you probably want at a database and a database adapter supported by Sequel[http://sequel.rubyforge.org]
This not only enables SessionStorage (persistent sessions between RSence restarts), but some plugins written for RSence depend on at least Sqlite.

=== Detailed list of ruby libraries used

* *rake*[http://rake.rubyforge.org]
  * Ruby build tool
  * Not necessarily required via ruby gems, if installed via a system-level package
* *rack*[http://rack.rubyforge.org]
  * Abstract ruby web server interface
  * A rack handler is also required. One of the following is suggested:
    * *unicorn*[http://unicorn.bogomips.org] :: Suggested for production deployment. Use Apache, Nginx or similar front-ends for virtual hosts, SSL and such.
    * *mongrel*[http://github.com/fauna/mongrel] :: Suggested for development use, also works for production when combined with a front-end proxy for virtual hosts etc.
    * *thin*[http://code.macournoyer.com/thin] ::  Alternative for development use.
    * *webrick*:: Bundled with ruby (no installation required). Very slow; use as last resort
* *json*[http://flori.github.com/json]:: Library for bi-directional JSON[http://json.org] conversion.
* *yaml*[http://yaml4r.sourceforge.net/doc]:: Library for handling YAML[http://www.yaml.org] files
* *randgen*:: C-optimized random string generator developed for RSence specifically
* *jsmin_c*:: C-optimized Javascript whitespace removal library; Ruby wrapper developed for RSence specifically; based on the original JSMin[http://www.crockford.com/javascript/jsmin.html]
* *jscompress*:: C-optimized Javascript compression and obfuscation library developed for RSence specifically
* *html_min*:: C-optimized HTML whitespace removal library developed for RSence specfically
* *cssmin*:: CSS whitespace removal library
* *sequel*[http://www.sequel.org]
  * Generic SQL database ORM
  * A Sequel driver for your preferred database is also needed:
    * *sqlite3-ruby*:: SQLite[http://www.sqlite.org] is a light-weight SQL library. Recommended for development and small projects.
    * Other database adapters compatible with Sequel are fine. Just configure RSence accordingly.
* *highline*:: Console-based menu prompt system by the init command.
* rmagick
  * Optional, but suggested, because RSence has RMagick -savvy features, like serving RMagick objects using tickets that are rendered only when requested.
  * Some plugins depend on it directly.


== Setting up RSence

The primary installation method of RSence is via RubyGems.

To ensure your RubyGems is up-to-date, run:
  sudo gem update --system

Even if RubyGems is up-to-date, ensure your installed gems are up-to-date, some of these are updated frequently. This will also update RSence release versions to the most recent version, if installed.
  sudo gem update

=== Install RSence

This will install RSence via RubyGems, the preferred method. All dependencies are installed too, except for the ones you already might have installed.
  gem install rsence

Optionally, you might want to contribute to RSence development, just clone or fork the GIT repository on Github:
  * http://github.com/rsence/rsence

When installed, ensure it works by exploring the help of the 'rsence' command, like:
  rsence
  rsence help
  rsence help version
  rsence help run
  rsence help init
etc..

=== Setting up

==== Creating a RSence project environment

To set up an environment for your RSence project, use the init command. In this example '/home/me/projects' is assumed as your project directory. Replace that with a path that matches your own environment. The RSence project directory must either be empty or will be created automatically.
  rsence init /home/me/projects/my_first_rsence_project

To see the options of the init command, use
  rsence help init

By default, init asks a few simple questions to write your configuration file. Just press enter, if you want to keep the suggested default options.

The questions are:
* Project Title
  * This is the name of your project. It's displayed as the title of the RSence web page.
* Session database connection string
  * This is a database connection string for persistent RSence session storage. It allows keeping sessions valid even if RSence is restarted.
  * You'll need the appropriate database adapter, most database engines are supported.
  * The simplest (and default) database connection string is for a local Sqlite database.
    * sqlite://db/ses.db
    * This default example string is for a database named 'ses.db' to be created in the 'db' subdirectory of your project directory.
  * The usual format is like any url, the following is for connecting to a mysql database named 'my_rsence_db' on the mysql server responding at 'localhost' on port '3306' using the username 'me' and password 'ins3cur3':
    * mysql://me:ins3cur3@localhost:3306/my_rsence_db
  * For more information, see:
    * http://sequel.rubyforge.org/rdoc/files/doc/opening_databases_rdoc.html
* HTTP Port
  * This is the port RSence listens to. It may be any free and valid port number.
* Interface TCP/IP address
  * This is the address RSence binds to.
  * '0.0.0.0' means RSence responds on all interface addresses configured on the computer.
  * '127.0.0.1' means RSence responds only on localhost. For testing and development, use 127.0.01 instead of 'localhost' in the web browser url field, because cookies can't be set for 'localhost'.
  * Any other IP address requires the same exact address to be configured on the computer RSence is running on.
* URI Prefix
  * This is by default the root directory, or /
  * Change this to another 'virtual directory', if you are configuring several RSence instances on a virtual host served via a HTTP proxy, like mod_rewrite on apache.

You may edit the conf/config.yaml at a later time to change these settings. The full list (and the defaults) are specified in the 'conf/default_conf.yaml' file in the installation directory of RSence.

Any differences in your local configuration replace the default. If the configuration option type is an Array, the defaults are not replaced, the defaults are appended to. If your configuration only has partial items of a Hash defined, only those are applied to the default.

==== Start RSence in the development mode with logs printed to the standard output:

The debug/development mode has the most verbose output and is the intended mode of RSence for development. Changes in your code are automatically (re)loaded and the javascript is not obfuscated or minimized in any way. Values also have human-readable id's.
  cd /home/me/projects/my_first_rsence_project
  rsence run -df

==== Open a web browser
* By default, the RSence listens on port 8001
* To test it, open the address http://127.0.0.1:8001/
* If everything works:
  * A welcome message is displayed
  * Check the "Don't show again" checkbox and click the "Close" button to make the 'welcome' plugin uninstall itself.

==== Stop RSence
Just press CTRL-C in the terminal, if RSence was started using the 'run' command.


== Modes of operation

RSence supports two main modes of operation: in the foreground and in the background. Each have various options. Use the 'rsence help run' and 'rsence help start' commands to read more about them.


=== Starting RSence as a foreground process.

The 'run' mode is well suited for development. Especially when combined with the -d and -f options.

Starting in foreground mode:
  rsence run

Starting in foreground mode with debug mode:
  rsence run -d

Starting in foreground mode with debug and logging in foreground:
  rsence run -df

Stopping in foreground mode: Press CTRL-C


=== Starting RSence as a daemon (background mode).

In the background mode, standard output and standard errors are logged in the 'log' directory of your project and the PID file is written in the 'run' directory. This mode of operation is best suited for production deployment and it's not available on Microsoft Windows, because full POSIX compliance is not available on Windows.
  rsence start

=== Stopping RSence in background mode
  rsence stop

=== Checking RSence status in background mode
  rsence status

=== To store the RSence sessions into the session database while in background mode
  rsence save

The sessions are also stored when stopping and restarting RSence. Use the 'save' command regularly from a cron script or equivalent in a production environment.

=== Restarting RSence in background mode
  rsence restart

=== Re-setting the sessions
This is needed only, if the session storage becomes corrupt in a development environment (changing value definitions and such). This invalidates all ongoing sessions.
Just apply the --reset-sessions option after the run, start or restart command in the command prompt.
  rsence restart --reset-sessions

The '-r' switch is equivalent to '--reset-sessions'

*NOTE: All the sessions currently connected clients are invalidated and need to reload the page*


=== Running in development mode
Just apply the -d option after the *run*, *start* or *restart* command in the command prompt.
  rsence restart -d

==== What does development mode do?
* Plugins are (re)loaded automatically in the background, if they are changed, disabled, added or removed.
  * This is also enabled with the -a switch (--auto-update)
* Javascript packages are automatically re-built, if they are changed.
  * This is also enabled with the -a switch (--auto-update)
* Much more verbose logging
* Code obfuscation / minimizing options are turned off.

=== Other command-line options
Just run this command to see the available options:
  rsence help <command>
example:
  rsence help run

=== Running RSence using rackup
  rackup conf/config.ru

=== Running RSence using unicorn
  unicorn conf/config.ru -c conf/unicorn.conf


== Plugin installation

If you followed the previous steps, you are ready to install some plugins.
* In development mode (see 4.4.), plugins are (re/un)loaded when:
  * Adding a new plugin into the plugins directory
  * Removing a plugin from the plugins directory
  * Disabling a plugin by creating a file or folder named "disabled" in the plugin's bundle directory
  * Enabling a plugin by removing a file or folder named "disabled" in the plugin's bundle directory
  * The plugin's ruby or yaml files are changed.

* In production mode, a RSence restart is required (see 4.4.), unless running with the '-a' ('--auto-update') option enabled. Enabling it is a good idea for production environments where the code is updated frequently. It enables nearly zero downtime, if code updates are thoroughly tested before being upgraded.

* By default, the "plugins" directory in the "rsence" directory is the only plugin directory.
  * Edit the configuration file to enable other directories.
* Sample plugins are available at http://rsence.org/


=== Installing plugins
Copy or move a plugin bundle directory into the "plugins" directory.

=== Un-Installing plugins
Move a plugin bundle out of the the "plugins" directory.

=== Temporarily disabling a plugin
Create an empty file named "disabled" in the plugin bundle to disable it.
  touch plugins/legacy/disabled


== Getting more information

* Explore http://rsence.org/
* Join our chat room on IRC (IRCNet and FreeNode):
  #rsence
* Email a question to us:
  info@rsence.org