Installing Oban UI

This guide is for Oban Web 1.X, to use Oban Web 2.X with Oban 2.0.X and Oban Pro see the guides on hexdocs.

The Oban UI is a web based dashboard built on Phoenix, Phoenix Live View, Ecto and of course; Oban. There are no additional dependencies.

1 Install Phoenix Live View

The Oban UI is built with Phoenix Live View and it relies on a working installation of Live View in your application. If you don’t have Live View installed, follow these instructions to get started.

2 Authenticate With Hex

The Oban UI is a delivered as a private package named oban_web, which is hosted on Hex PM. Before you can pull down the UI package you must authenticate with the oban organization.

mix hex.organization auth oban --key YOUR_OBAN_UI_LICENSE_KEY
You'll also need to authenticate on any development machines, build servers or in CI.

3 Install the ObanWeb Package

Once you’re authenticated you can add oban_web as a dependency in your application’s mix.exs:

{:oban_web, "~> 1.2", organization: "oban"}

Now fetch your dependencies:

mix deps.get

4 Add ObanWeb to Your Application

Add ObanWeb as a child within your supervision tree in application.ex:

def start(_type, _args) do
  oban_opts = Application.get_env(:my_app, Oban)
  oban_web_opts = Application.get_env(:my_app, ObanWeb)

  children = [
    MyApp.Repo,
    MyApp.Endpoint,
    {Oban, oban_opts},
    {ObanWeb, oban_web_opts}
  ]

  opts = [strategy: :one_for_one, name: MyApp.Supervisor]

  Supervisor.start_link(children, opts)
end

Configure ObanWeb for your application in config.exs:

config :my_app, ObanWeb, repo: MyApp.Repo, log: false

Currently following options are accepted:

  • :repo — your application’s Ecto repo, e.g. MyApp.Repo
  • :verbose — the log level that all queries will run with or false to disable logging, e.g. :debug

5 Mount the Dashboard

Add a live route to the dashboard within your application’s router:

scope "/" do
  pipe_through :browser

  live "/oban", ObanWeb.DashboardLive,
       layout: {ObanWeb.LayoutView, "app.html"}
end

In this example we’re using "/oban" as the mount point, but it can be anywhere you like. Note that we use scope/1 and not scope/2 to prevent prefixing the dashboard module with your scope’s namespace.

Be sure to restrict access to the dashboard via authentication, e.g. with Basic Auth!

6 Run Migrations (Optional)

To enable and optimize full text search you’ll also need to run a database migration. First, create a new migration:

mix ecto.gen.migration add_oban_web

As with Oban, you can delegate to ObanWeb.Migrations

defmodule MyApp.Repo.Migrations.AddObanWeb do
  use Ecto.Migration

  defdelegate up, to: ObanWeb.Migrations
  defdelegate down, to: ObanWeb.Migrations
end

Now run the migration to install an extension for full text search and add indexes:

mix ecto.migrate
The migration will attempt to install an extension; installing extensions may require super user permissions in your database.

7 Open the Dashboard

Installation is complete and you’re all set! Start your Phoenix server, point your browser to where you mounted Oban and start monitoring your jobs.


Trouble installing? Have questions?

Take a look at the FAQ to see if your issue is covered. If not, or if need any help, stop by the #oban channel in Elixir Slack.