Provides mount points for the Web dashboard with customization.

Customizing with a Resolver Callback Module

Implementing a Observer.Web.Resolver callback module allows you to customize the dashboard per-user, i.e. setting access controls.

As a simple example, let's define a module that makes the dashboard read only:

defmodule MyApp.Resolver do
  @behaviour Observer.Web.Resolver

  @impl true
  def resolve_access(_user), do: :read_only
end

Then specify MyApp.Resolver as your resolver:

scope "/" do
  pipe_through :browser

  observer_dashboard "/observer", resolver: MyApp.Resolver
end

See the Observer.Web.Resolver docs for more details.

Running Multiple Dashboards

A single router can mount more than one dashboard, each with its own path and :as name:

scope "/" do
  pipe_through :browser

  observer_dashboard "/observer", as: :observer_dashboard
  observer_dashboard "/admin/observer", as: :observer_admin_dashboard
end

On Mount Hooks

You can provide a list of hooks to attach to the dashboard's mount lifecycle. Additional hooks are prepended before Observer Web's own Authentication. For example, to run a user-fetching hook and an activation checking hook before mount:

scope "/" do
  pipe_through :browser

  observer_dashboard "/observer", on_mount: [MyApp.UserHook, MyApp.ActivatedHook]
end

Customizing the Socket Connection

Applications that use a live socket other than "/live" can override the default socket path in the router. For example, if your live socket is hosted at /observer_live:

socket "/observer_live", Phoenix.LiveView.Socket

scope "/" do
  pipe_through :browser

  observer_dashboard "/observer", socket_path: "/observer_live"
end

If your application is hosted in an environment that doesn't support websockets you can use longpolling as an alternate transport. To start, make sure that your live socket is configured for longpolling:

socket "/live", Phoenix.LiveView.Socket,
  longpoll: [connect_info: [session: @session_options], log: false]

Then specify "longpoll" as your transport:

scope "/" do
  pipe_through :browser

  observer_dashboard "/observer", transport: "longpoll"
end

Custom Pages

Beyond the built-in pillars, the dashboard can host custom pages implementing the Observer.Web.Page behaviour. Pages are registered with a route name and show up at the end of the navigation bar:

scope "/" do
  pipe_through :browser

  observer_dashboard "/observer", pages: [queue: MyApp.ObserverQueuePage]
end

See the Observer.Web.Page docs for how to build a page.

Content Security Policy

To secure the dashboard, or comply with an existing CSP within your application, you can specify nonce keys for images, scripts and styles.

You'll configure the CSP nonce assign key in your router, where the dashboard is mounted. For example, to use a single nonce for all three asset types:

observer_dashboard("/observer", csp_nonce_assign_key: :my_csp_nonce)

That instructs the dashboard to extract a generated nonce from the assigns map on the plug connection, at the :my_csp_nonce key.

Instead, you can specify different keys for each asset type:

observer_dashboard("/observer",
  csp_nonce_assign_key: %{
    img: :img_csp_nonce,
    style: :style_csp_nonce,
    script: :script_csp_nonce
  }
)