Add Phoenix LiveDashboard on a separate port (#4119)

## Summary
- Adds Phoenix LiveDashboard served on a dedicated Bandit instance,
configured via `ELECTRIC_LIVE_DASHBOARD_PORT`
- Dashboard is opt-in: not started unless the env var is set
- Fully isolated from the main Plug-based HTTP API

> **⚠️ Security note:** The dashboard endpoint is **completely
unauthenticated** and exposes internal system state (VM metrics, process
info, ETS tables, etc.). In production, operators **must** ensure the
dashboard port is firewalled or otherwise restricted to trusted networks
only.

## Test plan
- [x] Set `ELECTRIC_LIVE_DASHBOARD_PORT=4000` and verify dashboard loads
at `http://localhost:4000`
- [x] Verify main API on `ELECTRIC_PORT` is unaffected
- [x] Verify dashboard does not start when env var is unset

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: alco

.changeset/nice-taxis-shake.md

@@ -0,0 +1,5 @@
+---
+'@core/sync-service': patch
+---
+
+Add optional PhoenixLiveDashboard with configurable port to listen on.

README.md

@@ -32,6 +32,7 @@ Real-time sync for Postgres.
 - [What is Electric?](#what-is-electric)
 - [Getting Started](#getting-started)
 - [HTTP API Docs](#http-api-docs)
+- [Phoenix LiveDashboard](#phoenix-livedashboard)
 - [Developing Electric](#developing-electric)
   - [Mac setup](#mac-setup)
 - [Contributing](#contributing)
@@ -98,6 +99,20 @@ Again, see the [Quickstart](https://electric-sql.com/docs/quickstart) and the [D
 
 The HTTP API is defined in an [OpenAPI spec](https://swagger.io/specification/) in [website/electric-api.yaml](./website/electric-api.yaml).
 
+## Phoenix LiveDashboard
+
+Electric includes an optional [Phoenix LiveDashboard](https://github.com/phoenixframework/phoenix_live_dashboard) for real-time monitoring of the running system (VM metrics, process info, ETS tables, etc.).
+
+To enable it, set the `ELECTRIC_LIVE_DASHBOARD_PORT` environment variable:
+
+```sh
+ELECTRIC_LIVE_DASHBOARD_PORT=4000
+```
+
+The dashboard will be available at `http://localhost:4000` (or whichever port you choose). When the variable is not set, the dashboard is not started.
+
+> **WARNING: The LiveDashboard endpoint is completely unauthenticated.** Anyone with network access to the port can view internal system state. In production, you **must** restrict access to this port using firewall rules, network policies, or similar controls. Do not expose it to the public internet.
+
 ## Developing Electric
 
 We use [asdf](https://asdf-vm.com/) to install Elixir, Erlang, and Node.js. Versions are defined in [.tool-versions](.tool-versions).

packages/sync-service/.formatter.exs

@@ -1,5 +1,5 @@
 # Used by "mix format"
 [
   inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"],
-  import_deps: [:plug, :stream_data]
+  import_deps: [:plug, :stream_data, :phoenix]
 ]

packages/sync-service/config/runtime.exs

@@ -150,6 +150,7 @@ replication_stream_id =
   )
 
 prometheus_port = env!("ELECTRIC_PROMETHEUS_PORT", :integer, nil)
+live_dashboard_port = env!("ELECTRIC_LIVE_DASHBOARD_PORT", :integer, nil)
 
 call_home_telemetry_url =
   env!(
@@ -248,6 +249,7 @@ config :electric,
     env!("ELECTRIC_TELEMETRY_LONG_MESSAGE_QUEUE_DISABLE_THRESHOLD", :integer, nil),
   telemetry_statsd_host: statsd_host,
   prometheus_port: prometheus_port,
+  live_dashboard_port: live_dashboard_port,
   db_pool_size: env!("ELECTRIC_DB_POOL_SIZE", :integer, nil),
   replication_stream_id: replication_stream_id,
   replication_slot_temporary?: env!("CLEANUP_REPLICATION_SLOTS_ON_SHUTDOWN", :boolean, nil),
@@ -395,3 +397,31 @@ if Electric.telemetry_enabled?() do
     config :opentelemetry, processors: []
   end
 end
+
+# Phoenix LiveDashboard Endpoint Configuration
+#
+# WARNING: The dashboard is completely unauthenticated and exposes internal
+# system state (VM metrics, process info, ETS tables, etc.). In production,
+# ensure the dashboard port is firewalled or otherwise restricted to trusted
+# networks only.
+if live_dashboard_port do
+  dashboard_ip =
+    if env!("ELECTRIC_LISTEN_ON_IPV6", :boolean, false),
+      do: {0, 0, 0, 0, 0, 0, 0, 0},
+      else: {0, 0, 0, 0}
+
+  config :electric, Electric.LiveDashboard.Endpoint,
+    adapter: Bandit.PhoenixAdapter,
+    http: [
+      port: live_dashboard_port,
+      ip: dashboard_ip
+    ],
+    server: true,
+    render_errors: [
+      formats: [html: Electric.LiveDashboard.ErrorView],
+      layout: false
+    ],
+    live_view: [signing_salt: "r5zw+GcXjt3wP3Z/snFRqQ5uH2cm8Vb7ldc8t0POZdo="],
+    secret_key_base: Base.encode64(:crypto.strong_rand_bytes(48)),
+    pubsub_server: Electric.PubSub
+end

packages/sync-service/lib/electric/application.ex

@@ -53,7 +53,8 @@ defmodule Electric.Application do
       application_telemetry(config),
       [{Electric.StackSupervisor, Keyword.put(config, :name, Electric.StackSupervisor)}],
       api_server_children(config),
-      prometheus_endpoint(Electric.Config.get_env(:prometheus_port))
+      prometheus_endpoint(Electric.Config.get_env(:prometheus_port)),
+      live_dashboard_endpoint(Electric.Config.get_env(:live_dashboard_port))
     ])
   end
 
@@ -270,6 +271,15 @@ defmodule Electric.Application do
     ]
   end
 
+  defp live_dashboard_endpoint(nil), do: []
+
+  defp live_dashboard_endpoint(_port) do
+    [
+      {Phoenix.PubSub, name: Electric.PubSub},
+      Electric.LiveDashboard.Endpoint
+    ]
+  end
+
   @doc false
   # REQUIRED (but undocumented) public API for Phoenix.Sync
   def api_server do

packages/sync-service/lib/electric/config.ex

@@ -121,7 +121,8 @@ defmodule Electric.Config do
     shape_db_synchronous:
       Electric.ShapeCache.ShapeStatus.ShapeDb.Connection.default!(:synchronous),
     shape_db_cache_size: Electric.ShapeCache.ShapeStatus.ShapeDb.Connection.default!(:cache_size),
-    exclude_spans: MapSet.new()
+    exclude_spans: MapSet.new(),
+    live_dashboard_port: nil
   ]
 
   @installation_id_key "electric_installation_id"

packages/sync-service/lib/electric/live_dashboard/endpoint.ex

@@ -0,0 +1,44 @@
+defmodule Electric.LiveDashboard.Endpoint do
+  @moduledoc """
+  Phoenix Endpoint for serving LiveDashboard on a separate port.
+  This runs independently from the main Plug-based HTTP server.
+
+  **WARNING: This endpoint is completely unauthenticated.** It exposes internal
+  system state (VM metrics, process info, etc.). In production, ensure the
+  dashboard port is not publicly accessible — use firewall rules or network
+  policies to restrict access.
+  """
+
+  use Phoenix.Endpoint, otp_app: :electric
+
+  # LiveView socket for dashboard interactions
+  socket "/live", Phoenix.LiveView.Socket,
+    websocket: true,
+    longpoll: true
+
+  # Serve static assets for LiveDashboard
+  plug Plug.Static,
+    at: "/",
+    from: :phoenix_live_dashboard,
+    gzip: false,
+    only: ~w(assets fonts images priv)
+
+  # Session configuration for LiveView
+  plug Plug.Session,
+    store: :cookie,
+    key: "_live_dashboard_key",
+    signing_salt: "abc43s8Z",
+    same_site: "Lax"
+
+  # Parse request body for LiveView
+  plug Plug.Parsers,
+    parsers: [:urlencoded, :multipart, :json],
+    pass: ["*/*"],
+    json_decoder: Jason
+
+  plug Plug.MethodOverride
+  plug Plug.Head
+
+  # Route all requests to the LiveDashboard router
+  plug Electric.LiveDashboard.Router
+end

packages/sync-service/lib/electric/live_dashboard/error_view.ex

@@ -0,0 +1,10 @@
+defmodule Electric.LiveDashboard.ErrorView do
+  @moduledoc """
+  Error view for the LiveDashboard endpoint.
+  Handles rendering of HTTP errors.
+  """
+
+  def render(template, _assigns) do
+    Phoenix.Controller.status_message_from_template(template)
+  end
+end

packages/sync-service/lib/electric/live_dashboard/favicon_controller.ex

@@ -0,0 +1,12 @@
+defmodule Electric.LiveDashboard.FaviconController do
+  @moduledoc """
+  Simple controller to handle favicon requests.
+  Returns a 204 No Content response to avoid 500 errors.
+  """
+
+  use Phoenix.Controller, formats: [:html]
+
+  def show(conn, _params) do
+    send_resp(conn, 204, "")
+  end
+end

packages/sync-service/lib/electric/live_dashboard/router.ex

@@ -0,0 +1,26 @@
+defmodule Electric.LiveDashboard.Router do
+  @moduledoc """
+  Phoenix Router for LiveDashboard.
+  Mounts the dashboard at the root path.
+  """
+
+  use Phoenix.Router
+  import Phoenix.LiveDashboard.Router
+
+  pipeline :browser do
+    plug :accepts, ["html", "json"]
+    plug :fetch_session
+    plug :put_root_layout, html: {Phoenix.LiveDashboard.LayoutView, :root}
+    plug :protect_from_forgery
+    plug :put_secure_browser_headers
+  end
+
+  scope "/" do
+    pipe_through :browser
+
+    # Handle favicon requests gracefully
+    get "/favicon.ico", Electric.LiveDashboard.FaviconController, :show
+
+    live_dashboard "/", ecto_repos: []
+  end
+end