Skip to content

Commit 3689ef3

Browse files
sorentwosorentwo
committed
Document usage of standalone image
1 parent eb371f5 commit 3689ef3

File tree

5 files changed

+143
-1
lines changed

5 files changed

+143
-1
lines changed

‎README.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,21 @@ fully realtime.
7474
See the [installation guide](https://hexdocs.pm/oban_web/installation.html) for details on
7575
installing and configuring Oban Web for your application.
7676

77+
### Standalone Docker Image
78+
79+
A standalone Docker image is available for monitoring Oban without embedding the dashboard in your
80+
application:
81+
82+
```bash
83+
docker run -d \
84+
-e DATABASE_URL="postgres://user:pass@host:5432/myapp" \
85+
-p 4000:4000 \
86+
ghcr.io/oban-bg/oban-dash
87+
```
88+
89+
See the [standalone guide](https://hexdocs.pm/oban_web/standalone.html) for configuration options
90+
and details.
91+
7792
<!-- MDOC -->
7893

7994
## Contributing

‎guides/introduction/installation.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,11 @@ There are three installation mechanisms available:
99
- [Igniter Installation](#igniter-installation) fully automatic installation using igniter
1010
- [Manual Installation](#manual-installation) add Oban Web and handle all steps manually
1111

12+
> #### Standalone Docker Image {: .tip}
13+
>
14+
> If you want to monitor Oban without modifying your application, a [standalone Docker
15+
> image](standalone.md) is available that connects directly to your database.
16+
1217
## Semi-Automatic Installation
1318

1419
You can use the `oban_web.install` task without the `igniter.install` escript available.

‎guides/introduction/overview.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,3 +53,6 @@ fully realtime.
5353

5454
See the [installation guide](installation.md) for details on installing and configuring Oban Web
5555
for your application.
56+
57+
Alternatively, a [standalone Docker image](standalone.md) is available for monitoring Oban without
58+
embedding the dashboard in your application.

‎guides/introduction/standalone.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Standalone
2+
3+
A standalone Docker image is available for situations where you want an Oban dashboard without
4+
mounting Oban.Web within your application. This is useful for:
5+
6+
- Running the dashboard separately from your main application
7+
- Monitoring jobs created by [Oban for Python][oban-py] applications
8+
9+
[oban-py]: https://github.com/oban-bg/oban-py
10+
11+
> #### Interaction with Oban {: .info}
12+
>
13+
> The standalone dashboard operates in a monitoring-only capacity:
14+
>
15+
> - It connects to an existing database with Oban tables already present
16+
> - It does not run migrations or create tables
17+
> - It does not process jobs (`plugins: false`, `queues: false`)
18+
> - Queue scaling operations affect the connected application's queues
19+
>
20+
> When deploying to a production environment you should add authentication and potentially set
21+
> read only mode.
22+
23+
## Quick Start
24+
25+
Pull and run the image with your database connection:
26+
27+
```bash
28+
docker run -d \
29+
-e DATABASE_URL="postgres://user:pass@host:5432/myapp_prod" \
30+
-p 4000:4000 \
31+
ghcr.io/oban-bg/oban-dash
32+
```
33+
34+
Then visit `http://localhost:4000/oban`.
35+
36+
When connecting to a database on your host machine, use `host.docker.internal` instead of
37+
`localhost`:
38+
39+
```diff
40+
docker run -d \
41+
+ -e DATABASE_URL="postgres://host.docker.internal:5432/myapp_dev" \
42+
-p 4000:4000 \
43+
ghcr.io/oban-bg/oban-dash
44+
```
45+
46+
## Configuration
47+
48+
All configuration is done through environment variables:
49+
50+
| Variable | Required | Default | Description |
51+
| ----------------- | ---------- | --------- | ------------------------------- |
52+
| `DATABASE_URL` | Yes | — | PostgreSQL connection URL |
53+
| `POOL_SIZE` | No | `5` | Database connection pool size |
54+
| `PORT` | No | `4000` | HTTP port |
55+
| `OBAN_PREFIX` | No | `public` | Oban table schema prefix |
56+
| `OBAN_READ_ONLY` | No | `false` | Disable job actions when `true` |
57+
| `BASIC_AUTH_USER` | No | — | Basic auth username |
58+
| `BASIC_AUTH_PASS` | No | — | Basic auth password |
59+
| `LOG_LEVEL` | No | `info` | Log level |
60+
61+
## Authentication & Authorization
62+
63+
A simple authentication mechanism is built in and enabled with environment variables. Enable HTTP
64+
Basic Authentication by setting both `BASIC_AUTH_USER` and `BASIC_AUTH_PASS`:
65+
66+
```diff
67+
docker run -d \
68+
-e DATABASE_URL="postgres://host.docker.internal:5432/myapp" \
69+
+ -e BASIC_AUTH_USER="admin" \
70+
+ -e BASIC_AUTH_PASS="secret" \
71+
-p 4000:4000 \
72+
ghcr.io/oban-bg/oban-dash
73+
```
74+
75+
It's also possible to disable job actions such as cancel, retry, delete, etc. by enabling
76+
read-only mode:
77+
78+
```diff
79+
docker run -d \
80+
-e DATABASE_URL="postgres://host.docker.internal:5432/myapp" \
81+
+ -e OBAN_READ_ONLY="true" \
82+
-p 4000:4000 \
83+
ghcr.io/oban-bg/oban-dash
84+
```
85+
86+
## Oban Pro
87+
88+
To use [Oban Pro][pro] features like the Smart Engine, you'll need to build the image with your
89+
license key. The published `ghcr.io/oban-bg/oban-dash` image only includes the open source
90+
components.
91+
92+
Build with your Oban Pro license:
93+
94+
```bash
95+
git clone https://github.com/oban-bg/oban_web.git
96+
cd oban_web/standalone
97+
docker build \
98+
--build-arg OBAN_LICENSE_KEY="your_license_key" \
99+
-t oban-dash-pro .
100+
```
101+
102+
Then run your custom image:
103+
104+
```bash
105+
docker run -d \
106+
-e DATABASE_URL="postgres://host.docker.internal:5432/myapp" \
107+
-p 4000:4000 \
108+
oban-dash-pro
109+
```
110+
111+
[pro]: https://oban.pro
112+
113+
## Health Checks
114+
115+
The container exposes a health check endpoint at `/health` that returns `{"status":"ok"}`.
116+
Docker's built-in `HEALTHCHECK` is configured to monitor this endpoint automatically, making the
117+
image suitable for orchestration systems like Kubernetes or Amazon ECS.

‎mix.exs‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,7 @@ defmodule Oban.Web.MixProject do
6868
[
6969
"guides/introduction/overview.md",
7070
"guides/introduction/installation.md",
71+
"guides/introduction/standalone.md",
7172
"guides/advanced/filtering.md",
7273
"guides/advanced/limiting_access.md",
7374
"guides/advanced/metrics.md",
@@ -155,7 +156,8 @@ defmodule Oban.Web.MixProject do
155156
"deps.unlock --check-unused",
156157
"credo --strict",
157158
"test --raise"
158-
]
159+
],
160+
"dash.build": "cmd docker build -t oban-dash standalone"
159161
]
160162
end
161163
end

0 commit comments

Comments
 (0)