WSO2 WSF/Ruby Installation Guide

This document guides you on how to install the WSO2 Web Services Framework/Ruby extension, and run the server and client samples on Linux and Microsoft Windows operating systems.

Please send your feedback to the user mailing list: wsf-ruby-user@wso2.org. Kindly see Home page for subscription.

Installing WSO2 WSF/Ruby from Source on Linux
- Prerequisites
- Installation
Building and Installing WSO2 WSF/Ruby on Win32
- How to build WSF/Ruby under Windows from binaries
  - Requirements
  - Installing WSO2 WSF/Ruby extension as a Ruby extension
- How to build WSO2 WSF/Ruby under Windows from source
Run Samples

Installing WSO2 WSF/Ruby from Source on Linux

Prerequisites

WSO2 WSF/C [http://dist.wso2.org/products/wsf/c] Please see the INSTALL file of the WSO2 WSF/C to install WSO2 WSF/C.
Ruby version 1.8.5 or above. [http://ftp.ruby-lang.org/pub/ruby/1.8]

Installation

Before Install WSO2 WSF/RUBY, following configuration entries have to be added to the 'rbconfig.rb' that ship with ruby package.


     NOTE : run "ruby find_rbconfig.rb" in a console to find where this 'rbconfig.rb' file is.

    #---------------------------------------------------------------------------------

    CONFIG["WSFC_HOME"] = "your/wsfc/home/dir"
    CONFIG["WSF_LOG_DIR"] = "where/you/wish/log/file/should/be"
    CONFIG["WSF_LOG_LEVEL"] = "3"

    #---------------------------------------------------------------------------------

     NOTE: Above WSF_LOG_LEVEL entry can have one of the following values- 
               "0" - CRITICAL
               "1" - ERROR
               "2" - WARNING
               "3" - INFO
               "4" - DEBUG
               "5" - TRACE

Run "sh build.sh" to setup the extension. You may require super user privileges to run build.sh

Building and Installing WSO2 WSF/Ruby on Win32

How to build WSF/Ruby under Windows from binaries

Requirements

You need to download following dependency libraries:

libxml2 binary distribution - (Libxml2 2.6.30)
iconv binary distribution - (Iconv 1.9.2)
OpenSSL binary distribution - (openssl 0.98d, MSI distribution)
Ruby Binary - (Ruby 1.8.6, One click installer is prefereble)
Mysql Server [When using Reliable Messaging With MySql Database ] - (MySql 5.0 or above)

In addition you need to have visual studio installed on your system.

obtain libxml2 and iconv win32 binaries from [1].
obtain OpenSSL binary from [2] [the build system assumes that you install openssl from msi].
obtain MySql Server from [3].
obtain Ruby Bianry from [4].

[1] http://www.zlatkovic.com/pub/libxml/

[2] http://www.slproweb.com/products/Win32OpenSSL.html

[3] http://dev.mysql.com/downloads/

[4] http://www.ruby-lang.org/en/downloads/

NOTE: WSO2-WSF-Ruby-1.0.0 Win32 Binary Will be compiled using following version of dependency libraries.

Ruby 1.8.6
Libxml2 2.6.30
Iconv 1.9.2
openssl .98d (MSI)

Installing WSO2 WSF/Ruby extension as a Ruby extension

Now you should have the wso2-wsf-ruby binary pack with following structure.

    wso2-wsf-ruby-bin-1.0.0-win32
                |  
                +-- wsf_c
                |
                +-- doc
                |
                +-- samples
                |
                +-- lib

Execute install.rb file. (run "ruby install.rb" without quotes)
Add "\wsf_c\lib" directory to PATH environment variable.

Add the following entries to your rbconfig.rb file which is in your Ruby installation location.

 
        NOTE : run "ruby find_rbconfig.rb" in a console to find where this 'rbconfig.rb' file is.

        (use '/' or '\\' to to seperate directories.                                          |
         e.g. "E:/install/wsfc" or "E:\\install\\wsfc")

       #---------------------------------------------------------------------------------
       CONFIG["WSFC_HOME"] = "\\wsf_c"
       CONFIG["WSF_LOG_DIR"] = "where\\you\\wish\\log\\file\\should\\be"
       CONFIG["WSF_LOG_LEVEL"] = "3"
       #---------------------------------------------------------------------------------

        NOTE: Above WSF_LOG_LEVEL entry can have one of the following values- 

                  "0" - CRITICAL
                  "1" - ERROR
                  "2" - WARNING
                  "3" - INFO
                  "4" - DEBUG
                  "5" - TRACE

Now proceed to RUN SAMPLES section for a guide on how to run samples in WSO2 WSF/Ruby.

How to build WSO2 WSF/Ruby under Windows from source

Comment the following 3 lines at the top of config.h file.

       #if _MSC_VER != 1200

       #error MSC version unmatch

       #endif

       NOTE : run "ruby find_config_h.rb" in a console to find where this file is.

    Add the following entries to your rbconfig.rb file which is in your Ruby installation location.

        NOTE : run "ruby find_rbconfig.rb" in a console to find where this 'rbconfig.rb' file is.

        (use '/' or '\\' to to seperate directories.                                          |
         e.g. "E:/install/wsfc" or "E:\\install\\wsfc")

       #---------------------------------------------------------------------------------

       CONFIG["WSFC_HOME"] = "\\wsf_c"
       CONFIG["WSF_LOG_DIR"] = "where\\you\\wish\\log\\files\\should\\be"
       CONFIG["WSF_LOG_LEVEL"] = "3"

       #---------------------------------------------------------------------------------

       
        NOTE: Above WSF_LOG_LEVEL entry can have one of the following values- 

                  "0" - CRITICAL
                  "1" - ERROR
                  "2" - WARNING
                  "3" - INFO
                  "4" - DEBUG
                  "5" - TRACE

Make sure the WSFC_HOME/lib directory is added to the PATH environment variable.
If you have the Visual Studio command prompt installed on your computer, open it.
If you don't have the Visual Studio command prompt installed on your computer, open a command prompt and run vcvars32.bat.
Go to the WSO2 WSF/Ruby source directory
Run build.bat file in the WSO2 WSF/Ruby source directory.
Now proceed to RUN SAMPLES section for a guide on how to run samples in WSO2 WSF/Ruby.

Run Samples

It is required to have Rails Framework installed in your machine to run the Rails samples in
- samples/consumer/rails and
- samples/provide
Go to the samples/provider directory in the WSO2 WSF/Ruby binary/source distribution.
```
        cd samples/provider
```

Run deploy_samples.rb by executing the following command


        ruby deploy_samples.rb your_rails_application

Then you will have a rails application created in a directory called 'your_rails_application' relative to the currrent directory.
Go to the directory 'your_rails_application'
```
        cd your_rails_application
```
Then start the server executing the following command,
```
        run the ruby script/server
```
NOTE: If you are using rails 2.0.0 or above you may need to configure the database information in your rails application. You can find a guide on how to configure the database from the following link.
http://wiki.rubyonrails.com/rails/pages/TutorialStepOne
Now you are done deploying the provider samples .
Start a new shell or command prompt and go to the samples/consumer directory in the WSO2 WSF/Ruby binary/source distribution. Make sure WSO2 WSF/C libraries and its dependend libraries are included in the 'PATH' enviroment variable for new shell/command prompt as well.
```
       cd wsfc_ruby_source_installation/samples/consumer
```
Then run the echo sample by typing "ruby echo_client.rb" in command line or terminal. If your client and service are working fine, You will see the 'SUCCESSFUL' message
To run other samples please read the guide on README.SAMPLES file.

If you need any help with building or installation , send a mail to wsf-ruby-user@lists.wso2.org