Documentation for: v0.1.0 v0.2.0 v0.3.0 v0.4.0 v1.0.4

Web Console

Web Console is a set of debugging tools for your Rails application.

A debugging tool in the default error page.

An interactive console is launched automatically in the default Rails error page. It makes it easy to inspect the stack trace and execute Ruby code in the stack trace's bindings.

(Check out better_errors as a great alternative for any Rack application!)

A debugging tool in your controllers and views.

Drop <%= console %> anywhere in a view to launch an interactive console session and execute code in it. Drop console anywhere in a controller and do the same in the context of the controller action.

Requirements

Web Console has been tested on the following rubies.

• MRI Ruby 2.1.0
• MRI Ruby 2.0.0
• MRI Ruby 1.9.3

There is an experimental JRuby 1.7 support. See Installation section for more information.

Web Console is built explicitly for Rails 4.

Installation

To install it in your current application, add the following to your Gemfile.

group :development do
  gem 'web-console', '~> 2.0'
end

If you are running JRuby, you can get experimental support with adding a pre-release version of binding_of_caller.

group :development do
  gem 'web-console', '~> 2.0'

  gem 'binding_of_caller', '0.7.3.pre1'
end

After you save the Gemfile changes, make sure to run bundle install and restart your server for the Web Console to kick in.

Configuration

Today we have learned in the agony of war that great power involves great responsibility.

-- Franklin D. Roosevelt

Web Console is a powerful tool. It allows you to execute arbitrary code on the server, so you should be very careful, who you give access to it.

config.web_console.whitelisted_ips

By default, only requests coming from 127.0.0.1 are allowed.

config.web_console.whitelisted_ips lets you control which IP's have access to the console.

Let's say you want to share your console with 192.168.0.100. You can do this:

class Application < Rails::Application
  config.web_console.whitelisted_ips = %w( 127.0.0.1 192.168.0.100 )
end

From the example, you can guess that config.web_console.whitelisted_ips accepts an array of ip addresses, provided as strings. An important thing to note here is that, we won't push 127.0.0.1 if you manually set the option!

If you want to whitelist a whole network, you can do:

class Application < Rails::Application
  config.web_console.whitelisted_ips = '192.168.0.0/16'
end

Again, note that this network doesn't allow 127.0.0.1. If you want to access the console, you have to do so from it's external IP or add 127.0.0.1 to the mix.

Credits

• Shoutout to Charlie Somerville for better_errors! Most of the exception binding code is coming straight out of the better_errors project.

• Web Console wouldn't be possible without the work John Mair put in binding_of_caller. This is the technology that let us execute a console right where an error occurred.

• Thanks to Charles Oliver Nutter for all the JRuby feedback and support he has given us.

FAQ

I'm running JRuby and there's no console on the default error page.

You would also have to run you Rails server in JRuby's interpreted mode. Enable it with code snippet below, then start your development Rails server with rails server, as usual.

export JRUBY_OPTS=-J-Djruby.compile.mode=OFF

# If you run JRuby 1.7.12 and above, you can use:
# export JRUBY_OPTS=--dev

How to inspect local and instance variables?

The interactive console executes Ruby code. Invoking instance_variables and local_variables will give you what you want.