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

Web Console is currently in beta for 2.0.0. If you're searching for a stable version documentation, checkout the links above.

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 views.

Drop <%= console %> anywhere in a view to launch an interactive console session and execute code in it.

A VT100 compatible terminal.

Running rails console is quite handy. Sometimes, though, you can't easily access it, or maybe you want to easily share your session with a friend without configuring a remote desktop server.

Web Console can help you by running rails console (or any other commandline app), in full featured terminal right in the browser.

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.

Rubinius in 1.9 mode may work, but it hasn't been explicitly tested.

Web Console is built explicitly for Rails 4. Check out the web-console-rails3 project for a Rails 3 compatible build.

Installation

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

group :development do
  gem 'web-console', '2.0.0.beta3'
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

config.web_console.automount

If you want to automatically mount WebConsole::Engine, you can set this option to true. The terminal will be mounted at the location pointed by config.web_console.default_mount_path.

Defaults to false.

(Note that, this option used to default to true in the 1.0 days. We no longer automatically mount the web terminal at /console.).

config.web_console.default_mount_path

By default, the console will be mounted on /console.

(This happens only in the development and test environments!).

Say you want to mount the console to /debug, so you can more easily remember where to go, when your application needs debugging.

class Application < Rails::Application
  config.web_console.default_mount_path = '/debug'
end

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 just that one roommate, you like and his/her IP is 192.168.0.100.

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!

Now let's assume you like all of your roommates. Instead of enumerating their IP's, you can whitelist the whole private network. Now every time their IP's change, you'll have them covered.

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

You can see that config.web_console.whitelisted_ips accepts plains strings too. More than that, they can cover whole networks.

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.

config.web_console.command

By default, Web Console will run Rails.root.join('bin/rails console) to spawn you a fresh Rails console. If the relative bin/rails doesn't exist, rails console will be run instead.

One of the advantages of being a VT100 emulator is that Web Console can run most of your terminal applications.

Let say (for some reason) you can't run SSH on your server machine. You can run login instead to let users sign into the host system.

class Application < Rails::Application
  # You have to run /bin/login as root. That should worry you and you may work
  # around it by running ssh connecting to the same machine.
  config.web_console.command = 'sudo /bin/login'
end

Poor man's solution to SSH.

If you ever decide to use Web Console that way, use SSL to encrypt the traffic, otherwise all the input (including the negotiated username and password) can be easily sniffed!

config.web_console.term

By default, the Web Console terminal will report itself as xterm-color. You can override this option to change it with this option.

config.web_console.timeout

You may have noticed that Web Console client sends a lot of requests to the server. And by a lot, we really mean, a lot (every few milliseconds). We do this since we can't reliably predict when the output of your command execution will come available, so we poll for it.

This option control how much will the server wait on the process output pipe for input, before signalling the client to try again.

Maybe some day Web Sockets or SSE can be used for more efficient communication. Until that day, you can use long-polling. To enable it, use Puma as your development server and add the following to your configuration.

class Application < Rails::Application
  # You have to explicitly enable the concurrency, as in development mode,
  # the falsy config.cache_classes implies no concurrency support.
  #
  # The concurrency is enabled by removing the Rack::Lock middleware, which
  # wraps each request in a mutex, effectively making the request handling
  # synchronous.
  config.allow_concurrency = true

  # For long-polling, 45 seconds timeout for the development server seems
  # reasonable. You may want to experiment with the value.
  config.web_console.timeout = 45.seconds
end

Styling

If you would like to style the terminal a bit different than the default appearance, you can do so with the following options.

config.web_console.style.colors

Web Console supports up to 256 color themes, though most of the common terminal themes are usually 16 colors.

The default color theme is a white-on-black theme called light. For different appearance you may want to experiment with the other included color themes.

monokai the default Sublime Text colors
solarized_dark light version of the common solarized colors
solarized_light dark version of the common solarized colors
tango theme based on the tango colors
xterm the standard xterm theme

If you would like to use a custom theme, you may do so with the following syntax.

class Application < Rails::Application
  # First, you have to define and register your custom color theme. Each color
  # theme is mapped to a name.
  WebConsole::Colors.register_theme(:custom) do |c|
    # The most common color themes are the 16 colors one. They are built from 3
    # parts.

    # 8 darker colors.
    c.add '#000000'
    c.add '#cd0000'
    c.add '#00cd00'
    c.add '#cdcd00'
    c.add '#0000ee'
    c.add '#cd00cd'
    c.add '#00cdcd'
    c.add '#e5e5e5'

    # 8 lighter colors.
    c.add '#7f7f7f'
    c.add '#ff0000'
    c.add '#00ff00'
    c.add '#ffff00'
    c.add '#5c5cff'
    c.add '#ff00ff'
    c.add '#00ffff'
    c.add '#ffffff'

    # Background and foreground colors.
    c.background '#ffffff'
    c.foreground '#000000'
  end

  # Now you have to tell Web Console to actually use it.
  config.web_console.style.colors = :custom
end

config.web_console.style.font

You may also change the font, which is following the CSS font property syntax. By default it is large DejaVu Sans Mono, Liberation Mono, monospace.

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 occured.
Thanks to Charles Oliver Nutter for all the JRuby feedback and support he has given us.

FAQ

I'm running JRuby and /console doesn't load.

TL;DR Give it a bit of time, it will load.

While spawning processes is relatively cheap on MRI, this is not the case in JRuby. Spawning another process is slow. Spawning another JRuby process is even slower. Read more about the problem at the JRuby wiki.

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

Changing the colors is broken.

Some of the style sheets may be cached on the file system. Run rake tmp:cache:clear to clear those up.

How to view local and instance variables in an interactive console?

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

dheeraj510 / web-console