rsence-pre 2.1.0.1.pre

data/.yardopts

@@ -0,0 +1,10 @@
+  bin/rsence
+  lib/rsence.rb
+  lib/**/*.rb
+  plugins/**/*.rb
+  --no-private
+  --hide-void-return
+  --exclude lib/util/ruby19_fixes.rb
+  --exclude lib/http/rackup.rb
+  - conf/default_*.yaml INSTALL.rdoc LICENSE.txt VERSION
+    docs/*.rdoc

data/INSTALL.rdoc

@@ -0,0 +1,330 @@
+= Install Guide
+
+If you already have a working ruby environment and know what to do, the easiest way is just:
+
+ gem install rsence
+
+Otherwise, follow these instructions:
+
+
+== 1. 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.
+
+=== 1.1. Mac OS X
+
+==== 1.1.1 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
+
+==== 1.1.2. 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
+
+=== 1.2. 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
+
+=== 1.3. 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).
+
+==== 1.3.1. Install ruby 1.8.7:
+* Download Ruby 1.8.7-p249 (RC2) 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 from http://rubyinstaller.org/downloads
+  * Extract the included directories into the directory where you installed ruby.
+    * It's +C:\ruby+ by default.
+
+==== 1.3.2. Install RSence
+* In the command prompt, run:
+    gem update --system
+    gem install rsence
+    rsence help
+
+==== 1.3.3. 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 initenv 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
+
+==== 1.3.4. 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.
+
+
+=== 1.4. 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.
+
+
+== 2. 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.
+
+=== 2.1 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 initenv 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.
+
+
+== 3. 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
+
+=== 3.1. 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 initenv
+etc..
+
+=== 3.2. Setting up
+
+==== 3.2.1. Creating a RSence project environment
+
+To set up an environment for your RSence project, use the initenv 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 initenv /home/me/projects/my_first_rsence_project
+
+To see the options of the initenv command, use
+  rsence help initenv
+
+By default, initenv 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.
+
+==== 3.2.2. 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
+
+==== 3.3.3. 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.
+
+==== 3.3.4. Stop RSence
+Just press CTRL-C in the terminal, if RSence was started using the 'run' command.
+
+
+== 4. 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.
+
+
+=== 4.1. 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
+
+
+=== 4.2. 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
+
+=== 4.2.1 Stopping RSence in background mode
+  rsence stop
+
+=== 4.2.2 Checking RSence status in background mode
+  rsence status
+
+=== 4.2.3 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.
+
+=== 4.3. Restarting RSence in background mode
+  rsence restart
+
+=== 4.2.5. 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*
+
+
+=== 4.4. Running in development mode
+Just apply the -d option after the *run*, *start* or *restart* command in the command prompt.
+  rsence restart -d
+
+==== 4.4.1. 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.
+
+=== 4.5. Other command-line options
+Just run this command to see the available options:
+  rsence help <command>
+example:
+  rsence help run
+
+=== 4.6. Running RSence using rackup
+  rackup conf/config.ru
+
+=== 4.7. Running RSence using unicorn
+  unicorn conf/config.ru -c conf/unicorn.conf
+
+
+== 5. Plugin Deployment
+
+If you followed the previous steps, you are ready to deploy some software.
+* 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 deployed.
+
+* 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/
+
+
+=== 5.1. Deploying plugins
+Copy or move a plugin bundle directory into the "plugins" directory.
+
+=== 5.2. Un-deploying plugins
+Move a plugin bundle out of the the "plugins" directory.
+
+=== 5.3. Temporarily disabling a plugin
+Create an empty file named "disabled" in the plugin bundle to disable it.
+  touch plugins/legacy/disabled
+
+
+== 6. 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
+