Installation
Before continuing, be sure you have Oban up and running in your app!
Oban.Web
is built with Phoenix Live View and it relies on a working
installation of it in your application. If you don't have Live View
installed, follow these instructions to get started.
Oban.Web
is delivered as a hex package named oban_web
, which is published
privately under the oban
organization. The package is entirely self
contained—it doesn’t hook into your asset pipeline at all.
Before you can pull the package into your application you need to authenticate
with the oban
organization.
$ mix hex.organization auth oban --key YOUR_OBAN_LICENSE_KEY
⚠️ You'll also need to authenticate on any other development machines, build servers and CI instances.
Now that you're authenticated you're ready to add oban_web
as a dependency for
your application. Open mix.exs
and add the following line:
{:oban_web, "~> 2.1", organization: "oban"}
Now fetch your dependencies:
$ mix deps.get
This will fetch both oban_web
and oban_pro
, if you haven't already installed
oban_pro
.
Both the pro Lifeline
plugin and the web Stats
plugins are necessary for the
dashboard to function properly. Add them to your Oban configuration in
config.exs
:
config :my_app, Oban,
repo: MyApp.Repo,
queues: [alpha: 10, gamma: 10, delta: 10],
plugins: [
Oban.Pro.Plugins.Lifeline,
Oban.Web.Plugins.Stats
]
After configuration you can mount the dashboard within your application's
router.ex
:
# lib/my_app_web/router.ex
use MyAppWeb, :router
import Oban.Web.Router
...
scope "/" do
pipe_through :browser
oban_dashboard "/oban"
end
Here we're using "/oban"
as the mount point, but it can be anywhere you like.
After you've verified that the dashboard is loading you'll probably want to
restrict access to the dashboard via authentication, e.g. with Basic Auth.
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.
Running Multiple Dashboards
Applications that run multiple Oban instances can mount a dashboard for each
instance. Set the mounted dashboard's :oban_name
to match the corresponding
supervision tree's name. For example, given two configured Oban isntances,
Oban
and MyAdmin.Oban
:
config :my_app, Oban,
repo: MyApp.Repo,
name: Oban,
...
config :my_admin, Oban,
repo: MyAdmin.Repo,
name: MyAdmin.Oban,
...
You can then mount both dashboards in your router:
scope "/" do
pipe_through :browser
oban_dashboard "/oban", oban_name: Oban
oban_dashboard "/oban/admin", oban_name: MyAdmin.Oban
end
Note that the default name is Oban
, setting oban_name: Oban
in the example
above was purely for demonstration purposes.
Using LongPolling
If you're 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
oban_dashboard "/oban", transport: "longpoll"
end
Trouble installing? Have questions?
Take a look at the troubleshooting guide to see if your issue is covered. If not, or if need any help, stop by the #oban channel in Elixir Slack.