With Rails' web-console gem, how do you open a console in a view or controller, and what does config.web_console.permissions control?
answer
- console in a view or action
- rendered at the bottom, not in place
- one per request: DoubleRenderError
- localhost always allowed
- Docker bridge IP and "Cannot render console"
basics
~20 sCall console in a view or controller action and web-console appends a Ruby console, bound to that context, to the HTML page. config.web_console.permissions lists the extra IP addresses or networks allowed to see it; localhost is always allowed.
solid answer
~40 sweb-console defines `console` in `Kernel`. `<% console %>` in a template, or `console` in an action, records that binding, and the gem's middleware appends a console to the HTML response; it is not rendered where you call it. Only one call per request is allowed, and a second raises `WebConsole::DoubleRenderError`. Responses that are not HTML get no console. Because it runs arbitrary Ruby on the server, it only answers requests from permitted addresses. Localhost (`127.0.0.0/8`, `::1` and the IPv4-mapped loopback) is always allowed, and `config.web_console.permissions = "172.16.0.0/12"` adds more, for example a Docker bridge network. A refused request logs `Cannot render console from <ip>! Allowed networks: ...` while `whiny_requests` is on. The gem aborts boot outside development unless `config.web_console.development_only = false`.
go deeper
Recall that console in a view or action opens a browser console in that context and that only one is allowed per request.
Explain how the middleware injects the console into HTML responses and how permissions decide who gets one, including the Docker bridge case.
Treat web-console as remote code execution: keep it development-only, keep permissions narrow, and recognise the log line when it is refused.
Set the team's policy for in-browser consoles in shared development and review environments, balancing convenience against code-execution risk.
## Opening a console on purpose The exception page is not the only place web-console helps. You can ask for a console on **any** page. The gem defines `console` as a `Kernel` method: ```erb <%# app/views/carts/show.html.erb %> <% console %> <h1>Your cart</h1> <%= render @cart.line_items %> ``` ```ruby class CartsController < ApplicationController def show @cart = Cart.find(params[:id]) console # a console in this action's binding end end ``` How it behaves: 1. `console` stores the **caller's binding**, the view's or the action's, in a thread-local and returns `nil`, so `<% %>` and `<%= %>` both print nothing at that spot. 2. When the response comes back, **`WebConsole::Middleware`** sees a stored session and a response whose `Content-Type` includes `html`, and injects the console UI into the page. 3. The console appears at the bottom of the page. Each line you type is sent to the middleware's endpoint under `/__web_console` (`config.web_console.mount_point`) and evaluated in that binding: `@cart`, `params`, helpers in a view, locals. 4. **One per request.** A second `console` call in the same request raises **`WebConsole::DoubleRenderError`**. 5. JSON responses get no console, because the middleware injects it only when the `Content-Type` contains `html`. `binding.console` also exists, for when you want a specific binding without unwinding the stack. In the toy-store discount bug, a `console` call in `CartsController#show` lets you evaluate `@cart.line_items.map { [_1.sku, _1.discount_rate] }` against real data in the page you are looking at, with no terminal involved. ## Who may use it: config.web_console.permissions A web console is **remote code execution by design**. Anyone who can reach it can run Ruby as your app. So web-console checks the requesting IP address before injecting or evaluating anything: - **Always allowed:** `127.0.0.0/8`, `::1` and `::ffff:127.0.0.0/104`, the IPv4 and IPv6 loopback networks. - **`config.web_console.permissions`** adds a single address or a network, as a string or an array: `"192.168.0.100"`, `"192.168.0.0/16"`. - **`config.web_console.allowed_ips`** is accepted as an alternative name. The older **`whitelisted_ips`** is deprecated. The usual reason to touch it is **Docker**. When the app runs in a container, or a devcontainer, your browser's request reaches Rails from the bridge network's gateway address, not from `127.0.0.1`. The console then does not appear, and the log says why: ``` Cannot render console from 172.18.0.1! Allowed networks: 127.0.0.0/127.255.255.255, ::1, ... ``` The fix is to permit that network in `config/environments/development.rb`, for example `config.web_console.permissions = "172.16.0.0/12"`. Keep it as narrow as your setup allows. Set `config.web_console.whiny_requests = false` if you want that log line gone. ## Symptoms and causes | Symptom | Usual cause | |---|---| | No console on the page, and a `Cannot render console from ...` log line | The request came from an address outside the permitted networks | | No console on a JSON endpoint | The response's content type is not HTML | | `WebConsole::DoubleRenderError` | `console` was called twice in one request, for example in a view and in a partial | | Boot aborts with "Web Console is activated in the test environment" | The gem was moved out of the `:development` group | ## A short session 1. Add `console` to `CartsController#show` and reload the cart page. 2. Evaluate `@cart.line_items.map { [_1.sku, _1.discount_rate] }` in the console at the bottom. 3. Spot the item whose rate is `nil` and fix the data or the code. 4. Remove the `console` call, because a stray call would show the console to anyone permitted. ## Guardrails beyond the IP check | Guardrail | What it does | |---|---| | Gemfile group | The generated Gemfile puts `web-console` in `:development` only, and skips it entirely for `--api` apps | | `development_only` | At boot the gem **aborts** if it is loaded outside development, unless you set `config.web_console.development_only = false` | | Permissions | Only listed networks and localhost get a console | | Content type | Only HTML responses get the console injected | Never widen permissions to `0.0.0.0/0` or run the gem on a shared staging server. Anyone on that network could run Ruby in your app. ## Takeaway `console` in a view or action gives you a browser console bound to that exact context, injected at the bottom of the HTML page, once per request. `config.web_console.permissions` decides which addresses besides localhost may use it, and the Docker bridge address is the classic reason to set it.
- Why does web-console refuse to start when the app boots in the test environment?The `web_console.development_only` initializer aborts boot with a message when the gem is loaded outside development, unless `config.web_console.development_only = false` is set. The generated Gemfile keeps the gem in the `:development` group, so this only fires when someone moves it, for example into `:development, :test`.
- A view calls `console` and a partial it renders calls `console` again. What happens?The first call stores its binding in a thread-local. The second sees it already set and raises `WebConsole::DoubleRenderError`, so the page fails to render. Keep a single `console` call per request, and put it where the binding you need lives.
- <%= console %> renders the console exactly where the tag sits in the template.
- web-console permissions default to the local network, so Docker works out of the box.
- config.web_console.whitelisted_ips is the current name for the allowed networks.
- Calling console in a JSON action shows the console in the API response.
- Setting permissions to 0.0.0.0/0 is fine on a staging server behind a login.
- web-console only works on the exception page, not on normal pages.