Standalone

View Source

A standalone Docker image is available for situations where you want an Oban dashboard without mounting Oban.Web within your application. This is useful for:

  • Running the dashboard separately from your main application
  • Monitoring jobs created by Oban for Python applications

Interaction with Oban

The standalone dashboard operates in a monitoring-only capacity:

  • It connects to an existing database with Oban tables already present
  • It does not run migrations or create tables
  • It does not process jobs (plugins: false, queues: false)
  • Queue scaling operations affect the connected application's queues

When deploying to a production environment you should add authentication and potentially set read only mode.

Quick Start

Pull and run the image with your database connection:

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

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

When connecting to a database on your host machine, use host.docker.internal instead of localhost:

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

The image is built for both amd64 and arm64 architectures. If you need to specify a platform explicitly, use the --platform flag:

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

Configuration

All configuration is done through environment variables:

VariableRequiredDefaultDescription
DATABASE_URLYes—PostgreSQL connection URL
POOL_SIZENo5Database connection pool size
PORTNo4000HTTP port
OBAN_PREFIXNopublicOban table schema prefix
OBAN_READ_ONLYNofalseDisable job actions when true
BASIC_AUTH_USERNo—Basic auth username
BASIC_AUTH_PASSNo—Basic auth password
LOG_LEVELNoinfoLog level

Authentication & Authorization

A simple authentication mechanism is built in and enabled with environment variables. Enable HTTP Basic Authentication by setting both BASIC_AUTH_USER and BASIC_AUTH_PASS:

 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

It's also possible to disable job actions such as cancel, retry, delete, etc. 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

Oban Pro

To use Oban Pro features like the Smart Engine, you'll need to build the image with your license key. The published ghcr.io/oban-bg/oban-dash image only includes the open source components.

Build with your Oban Pro license:

git clone https://github.com/oban-bg/oban_web.git
cd oban_web/standalone
docker build \
  --build-arg OBAN_LICENSE_KEY="your_license_key" \
  -t oban-dash-pro .

Then run your custom image:

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

DNS Resolution

The Docker image ships with a built-in inetrc file that configures the BEAM VM to use the system's native DNS resolver. This ensures compatibility with platforms that use custom internal DNS, such as Fly.io and Kubernetes with CoreDNS.

No additional configuration is required. To provide your own inetrc file, mount it and override ERL_INETRC:

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

Health Checks

The container exposes a health check endpoint at /health that returns {"status":"ok"}. Docker's built-in HEALTHCHECK is configured to monitor this endpoint automatically, making the image suitable for orchestration systems like Kubernetes or Amazon ECS.