Web Dashboard

Web Dashboard#

Oban Web provides a real-time dashboard for monitoring queues, inspecting jobs, and viewing execution metrics. A standalone Docker image makes it easy to run the dashboard alongside your Python application.

Enable Metrics#

Before setting up the dashboard, enable metrics broadcasting in your oban.toml:

metrics = true

This broadcasts queue state, job execution metrics, and cron schedules via PostgreSQL pub/sub, which the dashboard uses for real-time updates.

Running the Dashboard#

Pull and run the standalone Docker image:

docker run -d \
  -e DATABASE_URL="postgres://user:pass@host.docker.internal:5432/myapp" \
  -p 4000:4000 \
  ghcr.io/oban-bg/oban-dash

Then visit http://localhost:4000/oban.

Note

Use host.docker.internal instead of localhost when connecting to a database on your host machine.

Configuration#

Configure the dashboard using environment variables:

Variable

Required

Default

Description

DATABASE_URL

Yes

—

PostgreSQL connection URL

POOL_SIZE

No

5

Database connection pool size

PORT

No

4000

HTTP port

OBAN_PREFIX

No

public

Oban table schema prefix

OBAN_READ_ONLY

No

false

Disable job actions when true

BASIC_AUTH_USER

No

—

Basic auth username

BASIC_AUTH_PASS

No

—

Basic auth password

Authentication#

Enable HTTP Basic Authentication for production deployments:

docker run -d \
  -e DATABASE_URL="postgres://user:pass@host.docker.internal:5432/myapp" \
  -e BASIC_AUTH_USER="admin" \
  -e BASIC_AUTH_PASS="secret" \
  -p 4000:4000 \
  ghcr.io/oban-bg/oban-dash

Read-Only Mode#

Disable job actions (cancel, retry, delete) by enabling read-only mode:

docker run -d \
  -e DATABASE_URL="postgres://user:pass@host.docker.internal:5432/myapp" \
  -e OBAN_READ_ONLY="true" \
  -p 4000:4000 \
  ghcr.io/oban-bg/oban-dash

Health Checks#

The dashboard exposes a health check endpoint at /health that returns {"status":"ok"}. Docker’s built-in HEALTHCHECK monitors this endpoint automatically.

Tuning Metrics#

The default metrics configuration works well for most deployments. For high-volume systems, you can tune these options:

[metrics]
interval = 1.0           # Broadcast frequency in seconds
estimate_limit = 50000   # Use estimates above this job count
cronitor_interval = 30   # Cron schedule broadcast frequency
counts_enabled = true    # Enable job state counts

Option

Default

Description

interval

1.0

How often metrics are broadcast (in seconds)

estimate_limit

50000

Job count threshold for switching to estimates

cronitor_interval

30

How often cron schedules are broadcast (seconds)

counts_enabled

true

Enable broadcasting job state counts

Estimated Counts#

Counting jobs in each state can become expensive at scale. When the count for a state exceeds estimate_limit, Oban switches to PostgreSQL’s statistics-based estimates. These are fast and accurate enough for dashboard displays, while exact counts are used for states with fewer jobs.

Lower the limit if you have many jobs and notice database load from count queries:

[metrics]
estimate_limit = 10000

Hybrid Elixir/Python Environments#

When running both Elixir and Python Oban workers against the same database, disable counts on the Python side to avoid duplicate job state counts in the dashboard:

[metrics]
counts_enabled = false

The Elixir instance will handle broadcasting job counts, while Python workers still report their own execution metrics (timing, throughput, etc.).

Contents