Documentation for: v2.0.0
Web Console is a debugging tool for your Ruby on Rails applications.
Web Console is meant to work as a Rails plugin. To install it in your current
application, add the following to your
group :development do gem 'web-console', '~> 2.0' end
After you save the
Gemfile changes, make sure to run
bundle install and
restart your server for the Web Console to kick in.
CRuby 1.9.2 and below is not supported.
JRuby needs to run in interpreted mode. You can enable it by:
export JRUBY_OPTS=-J-Djruby.compile.mode=OFF # If you run JRuby 1.7.12 and above, you can use: export JRUBY_OPTS=--dev
An unstable version of binding_of_caller is needed as the latest stable one
won't compile on JRuby. To install it, put the following in your application
group :development do gem 'binding_of_caller', '0.7.3.pre1' end
Only JRuby 1.7, is supported (no JRuby 9K support at the moment).
Internal errors like
ZeroDevisionError aren't caught.
The web console allows you to create an interactive Ruby session in your browser. Those sessions are launched automatically in case on an error, but they can also be launched manually in in any page.
For example, calling
console in a view will display a console in the current
page in the context of the view binding.
<% console %>
console in a controller will result in a console in the context of
the controller action:
class PostsController < ApplicationController def new console @post = Post.new end end
console invocation is allowed per request. If you happen to have
multiple ones, a
WebConsole::DoubleRenderError is raised.
Web Console allows you to execute arbitrary code on the server, so you should be very careful, who you give access to.
By default, only requests coming from IPv4 and IPv6 localhosts are allowed.
config.web_console.whitelisted_ips lets you control which IP's have access to
You can whitelist single IP's or whole networks. Say you want to share your
192.168.0.100. You can do this:
class Application < Rails::Application config.web_console.whitelisted_ips = '192.168.0.100' end
If you want to whitelist the whole private network, you can do:
class Application < Rails::Application config.web_console.whitelisted_ips = '192.168.0.0/16' end
Take a note that IPv4 and IPv6 localhosts are always allowed. This wasn't the case in 2.0.
When a console cannot be shown for a given IP address or content type, a messages like the following is printed in the server logs:
Cannot render console from 192.168.1.133! Allowed networks: 127.0.0.0/127.255.255.255, ::1
If you don't wanna see this message anymore, set this option to
class Application < Rails::Application config.web_console.whiny_requests = false end
If you wanna style the console yourself, you can place
style.css at a
directory pointed by
class Application < Rails::Application config.web_console.template_paths = 'app/views/web_console' end
You may wanna check the templates folder at the source tree for the files you may override.
Where did /console go?
The remote terminal emulator was extracted in its own gem that is no longer bundled with Web Console.
If you miss this feature, check out rvt.
Why I constantly get unavailable session errors?
All of Web Console sessions are stored in memory. If you happen to run on a multi-process server (like Unicorn) you may get unavailable session errors while the server is still running. This is because a request may hit a different worker (process) that doesn't have the desired session in memory.
To avoid that, if you use such servers in development, configure them so they server requests only out of one process.
How to inspect local and instance variables?
The interactive console executes Ruby code. Invoking
local_variables will give you what you want.
Why does console only appear on error pages but not when I call it?
This can be happening if you are using
Rack::Deflater. Be sure that
WebConsole::Middleware is used after
Rack::Deflater. The easiest way to do
this is to insert
Rack::Deflater as early as possible
class Application < Rails::Application config.middleware.insert(0, Rack::Deflater) end