Ensure you have Java 6 or above installed then download and extract the TorqueBox binary distribution and set a few environment variables.

$ wget http://torquebox.org/release/org/torquebox/torquebox-dist/2.3.0-SNAPSHOT/torquebox-dist-2.3.0-SNAPSHOT-bin.zip
...
2012-09-13 09:35:56 (1.61 MB/s) - `torquebox-dist-2.3.0-SNAPSHOT-bin.zip' saved [152039457/152039457]

$ unzip torquebox-dist-2.3.0-SNAPSHOT-bin.zip -d ~ 
...
  inflating: torquebox-2.3.0-SNAPSHOT/Rakefile
$ export TORQUEBOX_HOME=~/torquebox-2.3.0-SNAPSHOT
$ export JBOSS_HOME=$TORQUEBOX_HOME/jboss
$ export JRUBY_HOME=$TORQUEBOX_HOME/jruby
$ export PATH=$JRUBY_HOME/bin:$PATH

You'll likely want to place the exports somewhere that gets loaded automatically - ~/.bashrc, ~/.bash_profile, or wherever your operating system suggests placing user-specific environment variables.

Install Rails and create a new Rails example application.

$ mkdir -p ~/torquebox_examples/rails_example
$ cd ~/torquebox_examples/rails_example
$ gem install rails
...
Successfully installed rails-3.2.9
27 gems installed
$ rails new .
...
Using rails (3.2.9) 
Installing sass (3.2.3) 
Installing sass-rails (3.2.5) 
Installing therubyrhino_jar (1.7.4) 
Installing therubyrhino (2.0.2) 
Installing uglifier (1.3.0) 
Your bundle is complete! Use `bundle show [gemname]` to see where a bundled gem is installed.

Add a simple scaffolded resource, deploy it to TorqueBox, and run TorqueBox.

$ rails g scaffold post title body:text
...
      create      app/assets/stylesheets/posts.css.scss
      invoke  scss
      create      app/assets/stylesheets/scaffolds.css.scss
$ rake db:migrate
==  CreatePosts: migrating ====================================================
-- create_table(:posts)
   -> 0.0060s
   -> 0 rows
==  CreatePosts: migrated (0.0080s) ===========================================

$ torquebox deploy
Deployed: rails_example-knob.yml
    into: /Users/someone/torquebox-2.3.0-SNAPSHOT/jboss/standalone/deployments
$ torquebox run 
...
15:59:28,053 INFO  [org.jboss.as.server] (DeploymentScanner-threads - 2) JBAS018559: Deployed "rails_example-knob.yml"

Open http://localhost:8080 in your browser and you'll be greeted with the Rails "Welcome aboard" page. Navigate to http://localhost:8080/posts/ to see your scaffolded resource.

Now edit ~/torquebox_examples/rails_example/app/views/posts/index.html.erb then refresh the posts page in your browser and see your changes. Changes to your Rails application show up immediately in the browser, as expected. When you're done, press CTRL+C in the terminal to stop TorqueBox before continuing with the next steps.

Deploying multiple applications to TorqueBox is straightforward, but let's walk through the required steps. We'll create a Rack application to go with our Rails example application created earlier. If TorqueBox is still running stop it with CTRL+C in its terminal window before following the steps below.

$ mkdir -p ~/torquebox_examples/rack_example
$ cd ~/torquebox_examples/rack_example
$ gem install rack
Fetching: rack-1.4.1.gem (100%)
Successfully installed rack-1.4.1
1 gem installed

Now create a config.ru for our example rack application.

app = lambda { |env|
  [200, { 'Content-Type' => 'text/html' }, "Hello from Rack\n" ]
}
run app

Deploy the Rack application at a context-path of "/rack" since we already have the Rails application deployed at the root context.

$ torquebox deploy --context-path=/rack
Deployed: rack_example-knob.yml
    into: /Users/someone/torquebox-2.3.0-SNAPSHOT/jboss/standalone/deployments

Now you should be able to run TorqueBox and see both applications deployed.

$ torquebox run
...
19:25:38,049 INFO  [org.jboss.as.server] (DeploymentScanner-threads - 1) JBAS018559: Deployed "rails_example-knob.yml"
19:25:38,050 INFO  [org.jboss.as.server] (DeploymentScanner-threads - 1) JBAS018559: Deployed "rack_example-knob.yml"

Visit http://localhost:8080 and http://localhost:8080/rack/ to see that both your Rails and Rack applications are deployed and working.

Congratulations! You now know all the basics to proceed with the rest of this getting started guide when using a Mac or Linux.

Continue to Chapter 2, Adding TorqueBox Features.

Ensure you have Java 6 or above installed then download TorqueBox using your web browser from http://torquebox.org/release/org/torquebox/torquebox-dist/2.3.0-SNAPSHOT/torquebox-dist-2.3.0-SNAPSHOT-bin.zip. Right-click the downloaded zip in Windows Explorer and select Extract All. When prompted for a folder to extract the files to, choose your user's home directory (ie C:\Users\someone\).

After TorqueBox is extracted, we need to set a few environment variables. Find the Advanced System Settings dialog (in Windows 7 this is Control Panel -> System and Security -> System -> Advanced System Settings) and click the Environment Variables button. We want to add three new user environment variables. Add TORQUEBOX_HOME with a value of %HOME%\torquebox-2.3.0-SNAPSHOT. Add JBOSS_HOME with a value of %HOME%\torquebox-2.3.0-SNAPSHOT\jboss. Add JRUBY_HOME with a value of %HOME%\torquebox-2.3.0-SNAPSHOT\jruby. Also modify the Path environment variable by prepending %JRUBY_HOME%\bin; to the front of the current value. Click the OK button to save and close the Environment Variables dialog.

Now let's open up a Command Prompt to install Rails and create a new Rails example application. You can open a Command Prompt by clicking the Windows button in the bottom left and typing cmd in the search box.

> mkdir %HOME%\torquebox_examples\rails_example
> cd %HOME%\torquebox_examples\rails_example
> gem install rails
...
Successfully installed rails-3.2.9
27 gems installed
> rails new .
...
Using rails (3.2.9) 
Installing sass (3.2.5) 
Installing sass-rails (3.2.5) 
Installing therubyrhino_jar (1.7.4) 
Installing therubyrhino (2.0.2) 
Installing uglifier (1.3.0) 
Your bundle is complete! Use `bundle show [gemname]` to see where a bundled gem is installed.

Add a simple scaffolded resource, deploy it to TorqueBox, and run TorqueBox.

> rails g scaffold post title body:text
...
      create      app/assets/stylesheets/posts.css.scss
      invoke  scss
      create      app/assets/stylesheets/scaffolds.css.scss
> rake db:migrate
==  CreatePosts: migrating ====================================================
-- create_table(:posts)
   -> 0.0060s
   -> 0 rows
==  CreatePosts: migrated (0.0080s) ===========================================

> torquebox deploy
Deployed: rails_example-knob.yml
    into: C:\Users\someone\torquebox-2.3.0-SNAPSHOT\jboss\standalone\deployments
> echo Y | jruby -S torquebox run 
...
15:59:28,053 INFO  [org.jboss.as.server] (DeploymentScanner-threads - 2) JBAS018559: Deployed "rails_example-knob.yml"

Open http://localhost:8080 in your browser and you'll be greeted with the Rails "Welcome aboard" page. Navigate to http://localhost:8080/posts/ to see your scaffolded resource.

Now edit %HOME%\torquebox_examples\rails_example\app\views\posts\index.html.erb then refresh the posts page in your browser and see your changes. Changes to your Rails application show up immediately in the browser, as expected. When you're done, press CTRL+C in the terminal to stop TorqueBox before continuing with the next steps.

Deploying multiple applications to TorqueBox is straightforward, but let's walk through the required steps. We'll create a Rack application to go with our Rails example application created earlier. If TorqueBox is still running stop it with CTRL+C in its terminal window before following the steps below.

> mkdir %HOME%\torquebox_examples\rack_example
> cd %HOME%\torquebox_examples\rack_example
> gem install rack
Fetching: rack-1.4.1.gem (100%)
Successfully installed rack-1.4.1
1 gem installed

Now create a config.ru for our example rack application.

app = lambda { |env|
  [200, { 'Content-Type' => 'text/html' }, "Hello from Rack\n" ]
}
run app

Deploy the Rack application at a context-path of "/rack" since we already have the Rails application deployed at the root context.

> torquebox deploy --context-path=/rack
Deployed: rack_example-knob.yml
    into: C:\Users\someone\torquebox-2.3.0-SNAPSHOT\jboss\standalone\deployments

Now you should be able to run TorqueBox and see both applications deployed.

> echo Y | jruby -S torquebox run
...
19:25:38,049 INFO  [org.jboss.as.server] (DeploymentScanner-threads - 1) JBAS018559: Deployed "rails_example-knob.yml"
19:25:38,050 INFO  [org.jboss.as.server] (DeploymentScanner-threads - 1) JBAS018559: Deployed "rack_example-knob.yml"

Visit http://localhost:8080 and http://localhost:8080/rack/ to see that both your Rails and Rack applications are deployed and working.

Congratulations! You now know all the basics to proceed with the rest of this getting started guide when using Windows. The filesystem paths and command prompts shown in future chapters won't be Windows-specific, so be sure to translate any paths to the appropriate format before executing the example commands.

Continue to Chapter 2, Adding TorqueBox Features.

Ensure you have a recent JRuby installed then install the torquebox-server gem into the global gemset.

$ rvm install jruby-1.7.1
$ rvm use jruby-1.7.1@global
$ gem install torquebox-server

Create a directory and project-specific gemset for our example application.

$ mkdir -p ~/torquebox_examples/rails_example
$ cd ~/torquebox_examples/rails_example
$ rvm --rvmrc --create jruby-1.7.1@tb_rails_example

Change to the Rails example directory, trust the generated .rvmrc file when prompted, and install Rails.

$ cd ~/torquebox_examples/rails_example
====================================================================================
= NOTICE                                                                           =
====================================================================================
= RVM has encountered a new or modified .rvmrc file in the current directory       =
= This is a shell script and therefore may contain any shell commands.             =
=                                                                                  =
= Examine the contents of this file carefully to be sure the contents are          =
= safe before trusting it! ( Choose v[iew] below to view the contents )            =
====================================================================================
Do you wish to trust this .rvmrc file? (/Users/someone/torquebox_examples/rails_example/.rvmrc)
y[es], n[o], v[iew], c[ancel]> y
$ rvm gemset list

gemsets for jruby-1.7.1 (found in /Users/someone/.rvm/gems/jruby-1.7.1)
   global
=> tb_rails_example

$ gem install rails
...
Successfully installed rails-3.2.9
27 gems installed

Create a new Rails application, add a simple scaffolded resource, deploy it to TorqueBox, and run TorqueBox.

$ rails new .
...
Using rails (3.2.9) 
Installing sass (3.2.5) 
Installing sass-rails (3.2.5) 
Installing therubyrhino_jar (1.7.4) 
Installing therubyrhino (2.0.2) 
Installing uglifier (1.3.0) 
Your bundle is complete! Use `bundle show [gemname]` to see where a bundled gem is installed.
$ rails g scaffold post title body:text
...
      create      app/assets/stylesheets/posts.css.scss
      invoke  scss
      create      app/assets/stylesheets/scaffolds.css.scss
$ rake db:migrate
==  CreatePosts: migrating ====================================================
-- create_table(:posts)
   -> 0.0060s
   -> 0 rows
==  CreatePosts: migrated (0.0080s) ===========================================

$ torquebox deploy
Deployed: rails_example-knob.yml
    into: /Users/someone/.rvm/gems/jruby-1.7.1@global/gems/torquebox-server-2.3.0-SNAPSHOT-java/jboss/standalone/deployments
$ torquebox run 
...
15:59:28,053 INFO  [org.jboss.as.server] (DeploymentScanner-threads - 2) JBAS018559: Deployed "rails_example-knob.yml"

Open http://localhost:8080 in your browser and you'll be greeted with the Rails "Welcome aboard" page. Navigate to http://localhost:8080/posts/ to see your scaffolded resource.

Now edit ~/torquebox_examples/rails_example/app/views/posts/index.html.erb then refresh the posts page in your browser and see your changes. Changes to your Rails application show up immediately in the browser, as expected. When you're done, press CTRL+C in the terminal to stop TorqueBox before continuing with the next steps.

When you want to take advantage of TorqueBox-specific features, like we'll do in subsequent chapters, you'll need the torquebox gem in your application's Gemfile. However, since we're using torquebox-server under RVM to install TorqueBox, you'll want to ensure this gem is in the Gemfile for every application as well. If it's not you'll receive errors trying to use the torquebox because bundler will be unable to find the torquebox-server gem.

source 'https://rubygems.org'

gem 'rails', '3.2.9'

gem 'activerecord-jdbcsqlite3-adapter'
gem 'jruby-openssl'
gem 'json'

group :assets do
  gem 'sass-rails',   '~> 3.2.3'
  gem 'coffee-rails', '~> 3.2.1'
  gem 'therubyrhino'
  gem 'uglifier', '>= 1.0.3'
end

gem 'jquery-rails'

gem 'torquebox', '~> 2.3.0-SNAPSHOT'
gem 'torquebox-server', '~> 2.3.0-SNAPSHOT'

Deploying multiple applications to TorqueBox when using RVM and project-specific gemsets requires a small amount of extra work. To walk through the required steps, let's create a second Rack application to go with our Rails example application created earlier. If TorqueBox is still running stop it with CTRL+C in its terminal window before following the steps below.

$ mkdir -p ~/torquebox_examples/rack_example
$ cd ~/torquebox_examples/rack_example
$ rvm --rvmrc --create jruby-1.7.1@tb_rack_example
$ cd ~/torquebox_examples/rack_example
====================================================================================
= NOTICE                                                                           =
====================================================================================
= RVM has encountered a new or modified .rvmrc file in the current directory       =
= This is a shell script and therefore may contain any shell commands.             =
=                                                                                  =
= Examine the contents of this file carefully to be sure the contents are          =
= safe before trusting it! ( Choose v[iew] below to view the contents )            =
====================================================================================
Do you wish to trust this .rvmrc file? (/Users/someone/torquebox_examples/rack_example/.rvmrc)
y[es], n[o], v[iew], c[ancel]> y
$ rvm gemset list

gemsets for jruby-1.7.1 (found in /Users/someone/.rvm/gems/jruby-1.7.1)
   global
=> tb_rack_example
   tb_rails_example

$ gem install rack
Fetching: rack-1.4.1.gem (100%)
Successfully installed rack-1.4.1
1 gem installed

Now create a config.ru for our example rack application.

app = lambda { |env|
  [200, { 'Content-Type' => 'text/html' }, "Hello from Rack\n" ]
}
run app

Deploy the Rack application at a context-path of "/rack" since we already have the Rails application deployed at the root context.

$ torquebox deploy --context-path=/rack
Deployed: rack_example-knob.yml
    into: /Users/someone/.rvm/gems/jruby-1.7.1@global/gems/torquebox-server-2.3.0-SNAPSHOT-java/jboss/standalone/deployments

Now that two applications are deployed to TorqueBox, each with separate RVM gemsets, we hit an issue that trips up most users of RVM and TorqueBox. TorqueBox runs as a single process but RVM is really designed to have a separate process per project for gemsets to work out of the box. We can work around this by emulating the environment variables RVM sets when reading our .rvmrc in a torquebox.rb file for each application.

TorqueBox.configure do
  environment do
    GEM_HOME "#{ENV['rvm_path']}/gems/jruby-1.7.1@tb_rack_example"
    GEM_PATH "#{ENV['rvm_path']}/gems/jruby-1.7.1@tb_rack_example:#{ENV['rvm_path']}/gems/jruby-1.7.1@global"
  end
end

TorqueBox.configure do
  environment do
    GEM_HOME "#{ENV['rvm_path']}/gems/jruby-1.7.1@tb_rails_example"
    GEM_PATH "#{ENV['rvm_path']}/gems/jruby-1.7.1@tb_rails_example:#{ENV['rvm_path']}/gems/jruby-1.7.1@global"
  end
end

Now you should be able to run TorqueBox and see both applications deployed.

$ torquebox run
...
19:25:38,049 INFO  [org.jboss.as.server] (DeploymentScanner-threads - 1) JBAS018559: Deployed "rails_example-knob.yml"
19:25:38,050 INFO  [org.jboss.as.server] (DeploymentScanner-threads - 1) JBAS018559: Deployed "rack_example-knob.yml"

Visit http://localhost:8080 and http://localhost:8080/rack/ to see that both your Rails and Rack applications are deployed and working.

Congratulations! You now know all the basics to proceed with the rest of this getting started guide when using RVM. The most important thing to remember is to add the torquebox.rb that sets the GEM_HOME and GEM_PATH environment variables for each application that uses a project-specific gemset.

Continue to Chapter 2, Adding TorqueBox Features.