JBoss.orgCommunity Documentation

Chapter 1. First Steps

1.1. First Steps on Mac / Linux
1.1.1. Your First Rails Application
1.1.2. Subsequent Applications
1.2. First Steps on Windows
1.2.1. Your First Rails Application
1.2.2. Subsequent Applications
1.3. First Steps with RVM
1.3.1. Your First Rails Application
1.3.2. Subsequent Applications
1.4. First Steps with the Full Distribution
1.4.1. Your First Rails Application
1.4.2. Subsequent Applications

Choose the section below to follow based on your development environment - Windows users should follow Section 1.2, “First Steps on Windows”, RVM users should follow Section 1.3, “First Steps with RVM”, and regular Mac or Linux users should follow Section 1.1, “First Steps on Mac / Linux”.

If you need the full TorqueBox distribution for JavaEE applications, follow the Section 1.4, “First Steps with the Full Distribution”. The instructions are written with Linux in mind and will need to be modified slightly for usage on Windows.

If you use Ruby Version Manager (RVM), be sure to follow the Section 1.3, “First Steps with RVM” instructions and not the generic Mac / Linux instructions.

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/3.2.0/torquebox-dist-3.2.0-bin.zip
$ unzip torquebox-dist-3.2.0-bin.zip -d ~ 
$ export TORQUEBOX_HOME=~/torquebox-3.2.0
$ 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 -v "~>4.x"
...
Successfully installed rails-4.2.7.1
13 gems installed
$ rails new .
...
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-3.2.0/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-2.0.1.gem (100%)
Successfully installed rack-2.0.1
1 gem installed

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


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-3.2.0/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/3.2.0/torquebox-dist-3.2.0-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-3.2.0. Add JBOSS_HOME with a value of %HOME%\torquebox-3.2.0\jboss. Add JRUBY_HOME with a value of %HOME%\torquebox-3.2.0\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 -v "~>4.x"
...
Successfully installed rails-4.2.7.1
13 gems installed
> rails new .
...
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-3.2.0\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"

Why echo Y and jruby -S?

When stopping TorqueBox via CTRL+C, the Windows Command Prompt will ask you if you want to "Terminate batch job (Y/N)?". Piping echo Y into the command just prevents you from having to answer this prompt. We prefix the command with jruby -S because if we just used echo Y | torquebox run there's currently a bug where TorqueBox would get stuck in an infinite restart loop upon stopping.

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-2.0.1.gem (100%)
Successfully installed rack-2.0.1
1 gem installed

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


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-3.2.0\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-9.1.5.0
$ rvm use jruby-9.1.5.0@global
$ gem install torquebox-server -v 3.2.0

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-9.1.5.0@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-9.1.5.0 (found in /Users/someone/.rvm/gems/jruby-9.1.5.0)
   global
=> tb_rails_example

$ gem install rails -v "~>4.x"
...
Successfully installed rails-4.2.7.1
13 gems installed

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

$ rails new .
...
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-9.1.5.0@global/gems/torquebox-server-3.2.0-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 command because bundler will be unable to find the torquebox-server gem.


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-9.1.5.0@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-9.1.5.0 (found in /Users/someone/.rvm/gems/jruby-9.1.5.0)
   global
=> tb_rack_example
   tb_rails_example

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

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


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-9.1.5.0@global/gems/torquebox-server-3.2.0-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.



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.

Ensure you have Java 6 or above installed then download and extract JBoss Enterprise Application Platform 6.1 (EAP 6.1), the TorqueBox EAP overlay distribution, and set a few environment variables. The example below uses JBoss EAP 6.1.0.Alpha since it can be easily downloaded from the command line. If you'd like to use EAP 6.1.0 Final download it from http://www.jboss.org/jbossas/downloads instead of the wget command below.

$ wget http://download.jboss.org/jbosseap/6/jboss-eap-6.1.0.Alpha/jboss-eap-6.1.0.Alpha.zip
$ wget http://torquebox.org/release/org/torquebox/torquebox-dist/3.2.0/torquebox-dist-3.2.0-eap-overlay.zip
$ unzip jboss-eap-6.1.0.Alpha.zip -d ~
$ unzip torquebox-dist-3.2.0-eap-overlay.zip -d ~/jboss-eap-6.1
$ export JBOSS_HOME=~/jboss-eap-6.1
$ export JRUBY_HOME=$JBOSS_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 -v "~>4.x"
...
Successfully installed rails-4.2.7.1
13 gems installed
$ rails new .
...
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
==  CreatePosts: migrated (0.0080s) ===========================================

$ torquebox deploy
Deployed: rails_example-knob.yml
    into: /Users/someone/jboss-eap-6.1/standalone/deployments
$ torquebox run 
...
15:48:38,426 INFO  [org.jboss.as.server] (ServerService Thread Pool -- 43) JBAS018559: Deployed "rails_example-knob.yml" (runtime-name : "rails_example-knob.yml")

Rails 4 and ActiveRecord-JDBC

At the time of this writing, Rails 4 requires a prerelease version of the activerecord-jdbc gems. If you get an error when running migrations, try editing your Gemfile and change the version of activerecord-jdbcsqlite3-adapter to '1.3.0.beta2'. Afterwards run bundle install and try the migrations again.

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-2.0.1.gem (100%)
Successfully installed rack-2.0.1
1 gem installed

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


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/jboss-eap-6.1/standalone/deployments

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

$ torquebox run
...
22:37:35,963 INFO  [org.jboss.as.server] (ServerService Thread Pool -- 43) JBAS018559: Deployed "rails_example-knob.yml" (runtime-name : "rails_example-knob.yml")
22:37:35,964 INFO  [org.jboss.as.server] (ServerService Thread Pool -- 43) JBAS018559: Deployed "rack_example-knob.yml" (runtime-name : "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.