Documentation for: v0.1.0 v0.2.0
Web Console
There is no doubt that rails console
is one of the most useful commands,
Rails has to offer. However, sometimes you can't easily access it, or maybe
you want to share it with a coworker without configuring remote desktop
server.
This is where Web Console comes to the rescue. It gives you the same
rails console
experience, right in the browser. It's not just a tool that
let's you evaluate Ruby code, there are a lot of those. It's a VT100
compatible terminal, running rails console
.
You can see Web Console in action at this video.
Requirements
Web Console has been tested on the following rubies.
- MRI Ruby 2.0.0
- MRI Ruby 1.9.3
- JRuby 1.7.4
Rubunius in 1.9 mode may work, but it hasn't been tested.
Web Console has been built explicitly for Rails 4. For a Rails 3 compatible build, check out the web-console-rails3 project.
Installation
To install it in your current application, add the following to your Gemfile
.
group :development do
gem 'web-console', '~> 0.3.0'
end
After you save the Gemfile
changes, make sure to run bundle install
and
restart your server for the Web Console to take affect.
By default, it should be available in your development environment under
/console
. The route is not automatically mounted in a production environment
and we strongly encourage you to keep it that way.
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 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.default_mount_path
By default, the console will be automatically 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
config.web_console.automount
If you want to explicitly mount WebConsole::Engine
, you can prevent the
automatic mount by setting this option to false
.
config.web_console.command
By default, Web Console will run Rails.root.join('bin/rails console)
to
spawn you a fresh Rails console.
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
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 can be easily sniffed!
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 as a more efficient way of communication.
To enable long-polling, 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 seems reasonable.
config.web_console.timeout = 45.seconds
end
FAQ
I'm running JRuby and the console doesn't load.
While spawning processes is relatively cheap on MRI, this is not the case in JRuby. Spawning another processes in JRuby slow. Spawning another JRuby process is even slower. Read more at the JRuby wiki.
TL;DR Give it a bit of time, it will load.
Test Drive
If you just want to try the web-console, without having to go through the trouble of installing it, we provide a Docker container that does that for you.
To try it, install Docker first and then run the following snippet in your shell.
sudo docker build -t gsamokovarov/web-console github.com/gsamokovarov/web-console && sudo docker run -i -t !#:3