= NOTE: This installation manual isn't fully accurate at this time. = Installation If you already have a working ruby environment and know what to do, the easiest way is just: gem install rsence --pre Otherwise, follow these instructions: == 1. System Dependencies This is a list of system level dependencies. You only need to do this step once. === 1.1. Mac OS X This applies to all version of Mac OS X * Install a recent version of *XCode* from http://developer.apple.com/mac/ to install the essential development tools. * Install the most recent version of *MacPorts* from http://www.macports.org/ * Proceed with step 1.1.1. *or* 1.1.2. according to your version of Mac OS X ==== 1.1.1. Mac OS X 10.4 and 10.5 This step applies only to Mac OS X 10.4 Tiger and 10.5 Leopard * Install these packages using Terminal: sudo port install ruby +thread_hooks sudo port install rb-rubygems ==== 1.1.2 Mac OS X 10.6 This step applies only to Mac OS X 10.6 Snow Leopard * Install this package using Terminal: sudo port install sqlite3 === 1.2. Debian and Ubuntu GNU 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 === 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/download.html * Run the downloaded exe to install ruby * In the installation and destination prompt, check these options: * [x] Add Ruby executables to your PATH * [x] Associate .rb and .rbw files with this Ruby installation * Download and Install the Development Kit from http://rubyinstaller.org/download.html * 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 --pre rsence help ==== 1.3.3. Create RSence environment This assumes you have \my_projects directory. Also, the 'my_project' project directory is just for illustration purposes. Use something else instead of those. * In the command prompt, run: cd \my_projects rsence initenv my_project * Answer the quetions * 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, ether 127.0.0.1 instead. ==== 1.3.4. Windows limitations If you install the sqlite dll and the sqlite3-ruby gem, you'll gain persistent sessions and the "Warning: Session database is not available. Can't use persistent sessions" message will disappear when starting up rsence. It's not, however depended on in the default install, because it's not strictly required and makes the first installation much easier. Backgrounding is not yet implemented, because POSIX signals are not fully implemented in windows and backgrounding requires some windows service hooks. === 1.99. 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/ * Rake * Ruby replacement for make, needed for rubygems * Sqlite3 * Simple SQL library * RubyGems * Ruby package manager * A standard set of compilers and build tools * gcc, make etc. == 2. Ruby Dependencies The easiest way of installing a suggested set of these ruby gems is: gem install rsence-deps This is equivalent to: gem install rake highline rack mongrel soap4r rmagick json sequel sqlite3-ruby cssmin randgen jsmin_c jscompress html_min === 2.1 Detailed list of ruby dependencies * *rake* * Ruby build tool * Not necessarily required via ruby gems, if installed via a system-level package * http://rake.rubyforge.org/ * *rack* * Abstract ruby web server interface * http://rack.rubyforge.org/ * Additionally, you need a rack handler, one of the following is suggested: * *unicorn* * Suggested for production deployment * Use Apache, Nginx or similar front-ends for virtual hosts, SSL and such. * http://unicorn.bogomips.org/ * *mongrel* * Suggested for development use. * Solid * Pretty fast * Reliable * http://github.com/fauna/mongrel * *thin* * Quick * Not as stable or reliable as mongrel * http://code.macournoyer.com/thin/ * *webrick* * No installation needed, part of the standard library * Very slow * Use as last resort * *json* * Library for JSON - Ruby - JSON object conversion. * http://flori.github.com/json/ * http://json.org/ * *yaml* * Library for handling YAML files * Part of the standard library of Ruby 1.9 and newer * http://yaml4r.sourceforge.net/doc/ * http://www.yaml.org/ * *jsmin_c* * Javascript whitespace removal library * *jscompress* * Javascript compression and obfuscation library * *html_min* * HTML whitespace removal library * *cssmin* * CSS whitespace removal library * *sequel* * http://www.sequel.org/ * Additionally, you need a sequel driver for your database * *sqlite3-ruby* * Lightweight SQL library * Other database adapters compatible with sequel are fine. Just configure your setup accordingly. * *highline* * Not needed, if you configure manually. * soap4r * Optional, but required if you create SOAP services using the soap plugin * Not recommended * rmagick * Optional, but suggested == 3. Setting up RSence === 3.1. Download RSence There are two main options: *release* and *development*. Choose one of these: * *release*: * Latest stable release version. * Strongly suggested for development and production use. * Install as a gem: gem install rsence * *or* Manually download from: * http://rsence.org/ * *development*: * The latest stable bleeding-edge version. * Clone the GIT repository on github: * http://github.com/rsence/rsence === 3.2. Setting up ==== 3.2.1. Start RSence in the development mode with logs printed to the standard output: rsence run -df ==== 3.2.2. Configuration When starting up RSence for the first time, a configuration wizard is run. Just press return on the questions to use the default configuration. The default option is upper case: pressing return at a "Y/n" prompt will select "Y" ==== 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: * Currently: An empty, white page without error messages is a sign of success. * FIX 1: * A welcome message is displayed * Disables itself by touching a "disabled" file in its own directory. * Implement the standard "runonce" plugin. * FIX 2: * A setup review / configuration plugin * Implement the standard "setup" plugin. ==== 3.3.4. Stop the server Just press CTRL-C in the terminal. ==== 3.3.5. Manual configuration Edit the conf/config.yaml file. To see all available options at their default state, see conf/default_conf.yaml == 4. Controlling the process For development purposes (and the only option on Microsoft Windows): 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 *NOTE: on Microsoft Windows:* * No backgrounding is supported, unless *run.rb* is configured as a Service. === 4.1. Starting the server in background mode In the background mode, standard output and standard errors are logged in the var/log directory and the pidfile is written in the var/pid directory. rsence start === 4.2. Stopping the server in background mode rsence stop === 4.3. Checking the server status in background mode rsence status === 4.4. Restarting the server in background mode rsence restart === 4.5. Re-setting the sessions This is needed only, if the session storage becomes corrupt or you just want to start with a clean set of sessions. Just apply the --reset-sessions option after the run, start or restart command in the command prompt. rsence restart --reset-sessions *NOTE: All the sessions currently connected clients are invalidated and need to reload the page* === 4.6. Running in development mode Just apply the -d option after the *run*, *start* or *restart* command in the command prompt. rsence restart -d ==== 4.6.1. What does development mode do? * Plugins are reloaded automatically in the background, if they are changed, disabled, added or removed. * Javascript packages are automatically re-built, if they are changed. * Verbose logging === 4.7. Other command-line options Just run this command to see the available options: rsence help === 4.8. Running RSence using rackup rackup conf/config.ru === 4.9. 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.6.), 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 server restart is required (see 4.4.) * 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 rsence/plugins/legacy/disabled