You can generate a RhoConnect app with RhoStudio or with the
rhoconnect utility command line tool.
In RhoStudio, select File->New->Project…
The New Project window opens. Select the RhoConnect application wizard and click the Next button.
Enter the name for your RhoConnect application in Project name. You may specify a specific folder for your destination where your project is stored, by default, the destination is your RhoStudio workspace folder. Then press the Finish button.
rhoconnect utility is a command line tool for generating RhoConnect applications and source adapters.
The app name is passed as a parameter. The
rhoconnect utility will generate a directory for your application with all the necessary files to get started. We will start with running
rhoconnect help app to see the usage:
Usage: rhoconnect app NAME Generates a new rhoconnect application.
$ rhoconnect app storeserver Generating with app generator: [ADDED] storeserver/config.ru [ADDED] storeserver/settings/settings.yml [ADDED] storeserver/settings/license.key [ADDED] storeserver/application.rb [ADDED] storeserver/Rakefile [ADDED] storeserver/Gemfile [ADDED] storeserver/spec/spec_helper.rb
Here’s a basic rundown of each of the files that were just generated:
class << selfblock.
After generating the application, you might be asked to change directories to your application directory and run bundle install. For example, you would run these commands:
$ cd storeserver $ bundle install
In rhoconnect versions 3.2 and higher, a ruby utility called thor routes all rake-like tasks through a custom command-line interface. All tasks are used via the rhoconnect gem’s command line interface.
To issue commands this way, type
rhoconnect followed by the task you wish to perform. To see a list of all the tasks you can issue with
$ rhoconnect help Tasks: rhoconnect app NAME # Generate a new rhoconnect application rhoconnect attach # Attach to rhoconnect console rhoconnect console [environment] # Run rhoconnect console rhoconnect dtach-about # About dtach rhoconnect dtach-install # Install dtach program from sources rhoconnect flushdb # Flush data store - WARNING: THIS REMOVES ALL DATA IN RHOCONNECT rhoconnect get-token # Fetch current api token from rhoconnect rhoconnect help [TASK] # Describe available tasks or one specific task rhoconnect redis-about # About redis rhoconnect redis-attach # Attach to redis dtach socket rhoconnect redis-download # Download redis release 2.4.10 rhoconnect redis-install # Install the latest verison of Redis from Github (requires git, duh) rhoconnect redis-restart # Restart redis on localhost:6379 rhoconnect redis-start # Start redis on localhost:6379 rhoconnect redis-stop # Stop redis running on localhost:6379 rhoconnect restart [options] # Alias for `rhoconnect stop; rhoconnect start` rhoconnect secret # Generate a cryptographically secure secret session key rhoconnect set-admin-password # Set the admin password rhoconnect source NAME # Generate a new source adapter rhoconnect start [options] # Start rhoconnect server rhoconnect stop # Stop rhoconnect server rhoconnect update # Update an existing application to the latest rhoconnect release rhoconnect version # Display rhoconnect version rhoconnect web # Launch the web console in a browser
rhoconnect war command is available only if you switch to jruby, such as using the command
rvm use jruby.
rhoconnect start and
rhoconnect restart have the following options.
-p, [--port=N] # Use port (default: 9292) -r, [--redis=REDIS] # Redis server settings: (default: localhost:6379) -P, [--push-server=PUSH_SERVER] # Push server settings (default: http://someappname@localhost:8675/) -t, [--api-token=API_TOKEN] # API token (default: my-rhoconnect-token) -f, [--config=CONFIG] # /path/to/rhoconnect/settings.yml file -l, [--licenseflie=LICENSEFLIE] # /path/to/license.key file
If you’re using MacOS / Linux, install dtach on your path before running any of the rhoconnect tasks. DTach is a simple utility which runs processes in a detached state so you can re-attach your console later.
$ cd storeserver $ rhoconnect dtach-install
Next, you will need to setup and start a redis server:
$ rhoconnect redis-install $ rhoconnect redis-start
The server will show that it is running on the console.
Open a new console window (since the redis server is running in the previous console window). Then change directories to your rhoconnect application and start the application.
$ cd storeserver $ rhoconnect start
You can also start RhoConnect in a directory that does not contain a RhoConnect source adapter application. This is useful for RhoConnect plugin developers, who do not write a RhoConnect source adapter application: they can start a RhoConnect server from an empty directory.
$ cd (an empty directory) $ rhoconnect start
When you start RhoConnect in a directory that does not contain a rhoconnect source adapter application, a hidden settings file, .rhoconnect.yml, is created in your user home directory. Here is a partial sample listing.
:development: &70196107903780 :syncserver: http://localhost:9393 :redis: localhost:6379 :push_server: http://someappname@localhost:8675/ :api_token: my-rhoconnect-token :secret: !binary |- ... :test: *70196107903780 :production: *70196107903780
Once .rhoconnect.yml has been created in your user home directory, you can manually modify it for the next time you start RhoConnect. For example, you could change the port upon which the syncserver runs.
Running RhoConnect this way uses the default license key in the RhoConnect gem. You can use other license keys by using the
-l option in the
rhoconnect start command.
If everything went well when you started RhoConnect, you should see the following in your console:
[05:47:10 PM 2011-04-19] Rhoconnect Server v3.0.0 started...
To open the web console, navigate to http://localhost:9292/ in your browser or run:
$ rhoconnect web
It is possible to create Java WAR containers for your Rhoconnect application that can be deployed into the Java App Servers (for example, JBoss). To create the executable WAR container, execute the following command in your app’s root directory:
$ cd storeserver $ rhoconnect war
This will build the WAR file named
RhoConnect applications come with many useful rhoconnect tasks for administrative and development workflows. Some common ones are:
rhoconnect dtach-install – (Mac OS / Linux only) This will install dtach to /usr/local/bin.
rhoconnect redis-install – This will install to the system. On Mac OS / Linux, it will attempt to install in ‘/usr/local/bin’ (on windows, C:\redis-
rhoconnect set-admin-password – Set the RhoConnect administrator password. The default password is blank ‘’.
rhoconnect get-token – Get a RhoConnect API token to use for calling the RhoConnect REST API.
On Mac OS / Linux, you need to install dtach (i.e. by running
rhoconnect dtach-install) to run the following tasks:
rhoconnect redis-start – This will launch a redis server in a new console.
rhoconnect redis-stop – Stop the currently-running redis server.
rhoconnect redis:attach – (Mac OS / Linux only) Attach to a currently-running redis server.
rhoconnect start – Start the RhoConnect application in a new console. This requires a running redis server.
rhoconnect stop – Stop the currently-running RhoConnect application.
rhoconnect attach – (Mac OS / Linux only) Attach to a currently-running RhoConnect application.
Some other useful development tasks:
rhoconnect spec – Run all source adapter specs in spec/sources/.
rhoconnect web – Open the RhoConnect web console in a browser.
Connecting to a backend service with RhoConnect requires that you write a small amount of code for the query, create, update and delete operations of your particular enterprise backend. The collection of the code for these operations is called a source. You can create source for your RhoConnect application two ways:
RhoConnect source adapter: generate a Ruby code source adapter from RhoStudio or from the command line, similar to how you generate a RhoConnect app. This source adapter contains code for the query, create, update and delete operations.
RhoConnect plugin: write the source code (the query, create, update and delete operations) into your backend application, and plug a RhoConnect plugin in the application. The plugin is written in the language that matchs your backend application, such as Java or .NET.
As of version 4.0 of rhoconnect, rake tasks will be deprecated!!
Each RhoConnect (v.3.1 and lower) application uses rake to manage development tasks such as starting/stopping the app, starting resque workers, and running specs.
To run a RhoConnect rake task, simply type
rake the-task-to-run in your RhoConnect application’s root directory.
Here is a complete list of the rake tasks available in a RhoConnect v.3.1 and lower application:
$ cd storeserver $ rake -T (in ~/storeserver) rake dtach:about # About dtach rake dtach:install # Install dtach 0.8 from source rake redis:about # About redis rake redis:attach # Attach to redis dtach socket rake redis:download # Download package rake redis:install # Install the latest version of Redis from Github (requires git, duh) rake redis:restart # Restart redis rake redis:start # Start redis rake redis:stop # Stop redis rake resque:work # Start a Resque worker rake resque:workers # Start multiple Resque workers. rake rhoconnect:attach # Attach to rhoconnect console rake rhoconnect:clean_start # Clean rhoconnect, get token, and create new user rake rhoconnect:create_user # Creates and subscribes user for application in rhoconnect rake rhoconnect:delete_device # Deletes a device from rhoconnect rake rhoconnect:delete_user # Deletes a user from rhoconnect rake rhoconnect:flushdb # Flush data store - WARNING: THIS REMOVES ALL DATA IN RHOCONNECT rake rhoconnect:get_token # Fetches current api token from rhoconnect rake rhoconnect:reset # Reset the rhoconnect database (you will need to run rhoconnect:get_token afterwards) rake rhoconnect:reset_refresh # Reset source refresh time rake rhoconnect:restart # Alias for `rake rhoconnect:stop; rake rhoconnect:start` rake rhoconnect:set_admin_password # Sets the admin password rake rhoconnect:spec # Run source adapter specs rake rhoconnect:start # Start rhoconnect server rake rhoconnect:stop # Stop rhoconnect server rake rhoconnect:war # Build executable WAR file to be used in Java App Servers rake rhoconnect:web # Launch the web console in a browser - uses :syncserver: in settings.yml
Below is provided a list of rake tasks and their corresponding RhoConnect v.3.2+ command.
|rake Command||rhoconnect command|
|rake -T||rhoconnect help|
|rake rhoconnect:attach||rhoconnect attach|
|rake rhoconnect:clean_start||rhoconnect clean-start (not available for v.4.0 or above)|
|rake rhoconnect:clean_user||rhoconnect clean-user (not available for v.4.0 or above)|
|rake rhoconnect:delete_device||rhoconnect delete-device (not available for v.4.0 or above)|
|rake rhoconnect:delete_user||rhoconnect delete-user (not available for v.4.0 or above)|
|rake rhoconnect:flushdb||rhoconnect flushdb|
|rake rhoconnect:get_token||rhoconnect get-token|
|rake rhoconnect:reset||rhoconnect reset (not available for v.4.0 or above)|
|rake rhoconnect:reset_refresh||rhoconnect reset-refresh (not available for v.4.0 or above)|
|rake rhoconnect:restart||rhoconnect restart|
|rake rhoconnect:set_admin_password||rhoconnect set-admin-password|
|rake rhoconnect:spec||rhoconnect spec|
|rake rhoconnect:start||rhoconnect start|
|rake rhoconnect:stop||rhoconnect stop|
|rake rhoconnect:war||rhoconnect war|
|rake rhoconnect:web||rhoconnect web|
|rake dtach:about||rhoconnect dtach-about|
|rake dtach:install||rhoconnect dtach-install|
|rake redis:about||rhoconnect redis-about|
|rake redis:attach||rhoconnect redis-attach|
|rake redis:download||rhoconnect redis-download|
|rake redis:install||rhoconnect redis-install|
|rake redis:restart||rhoconnect redis-restart|
|rake redis:start||rhoconnect redis-start|
|rake redis:stop||rhoconnect redis-stop|