Installation

Copy Markdown View Source

This is the exact day-0 path for a Phoenix host app. The library owns internal pages and runtime helpers. Your host owns auth, display policy, the outer router scope, and the database commands it runs.

Oban Powertools ships a native, host-owned operator shell at /ops/jobs.

0. Start From A Fresh Phoenix Host

The paved road starts from a real Phoenix app:

mix phx.new my_app --database postgres

1. Add Dependencies

Add Oban Powertools to your host app. oban_web is optional, and you only add it if you want the nested read-only bridge at /ops/jobs/oban.

def deps do
  [
    {:oban_powertools, "~> 0.5"},
    {:oban_web, "~> 2.10", optional: true}
  ]
end

2. Run the Installer

Run the generator-backed installer:

mix oban_powertools.install

The installer adds starter host wiring for repo, auth_module, and display_policy, creates Powertools migrations, and mounts the library route tree under a host-owned /ops/jobs scope. The generated MyAppWeb.ObanPowertoolsAuth and MyAppWeb.ObanPowertoolsDisplayPolicy modules are thin starter seams owned by the host app.

3. Add the Required Host Runtime Config

Keep the generated repo, auth_module, and display_policy wiring in place:

config :oban_powertools,
  repo: MyApp.Repo,
  auth_module: MyAppWeb.ObanPowertoolsAuth,
  display_policy: MyAppWeb.ObanPowertoolsDisplayPolicy

auth_module: MyAppWeb.ObanPowertoolsAuth is host-owned. display_policy: MyAppWeb.ObanPowertoolsDisplayPolicy is also host-owned and required before native pages render policy-sensitive values. Neither starter seam should be treated as a finished production policy.

4. Confirm the Router Mount

Your host owns the outer browser scope. The library owns only the nested routes mounted inside it:

scope "/ops/jobs" do
  pipe_through(:browser)

  require ObanPowertools.Web.Router
  ObanPowertools.Web.Router.oban_powertools_routes("/oban")
end

That mount gives you native Powertools pages at /ops/jobs and the optional read-only bridge at /ops/jobs/oban. Native Powertools pages are the supported mutation surface.

5. Compile The Generated Host Once

Before calling installation successful, compile the generated host:

mix compile

6. Run The Required Database Path

mix oban_powertools.install generates migrations for audit, idempotency, limiters, cron, workflow, and lifeline tables. Run them in your host app:

mix ecto.migrate

Use mix ecto.reset instead when you want a clean local reset plus seeds. The day-0 contract is not complete until one of those database paths succeeds.

7. Boot The Host Once

Run one bounded boot check before the first operator action:

mix phx.server

If the host boots and /ops/jobs renders through your browser pipeline, auth seam, and display policy seam, the paved road is ready for the first native session.

8. Optional oban_web Dependency

oban_web is optional. If you install it, Powertools mounts the nested bridge at /ops/jobs/oban. That bridge remains read-only and narrower than the native Powertools pages. The host owns router scope, browser pipeline, auth, display policy, and runtime config.

9. Continue To The First Operator Session

Move on to First Operator Session once the host can compile, migrate, and boot with the config and router contract above.