https://github.com/hannes221/rq-dashboard-fast
Redis Queue Dashboard based on FastAPI
https://github.com/hannes221/rq-dashboard-fast
dashboard docker docker-image fastapi python redis redis-queue redis-queue-monitor rq rq-dashboard
Last synced: 2 months ago
JSON representation
Redis Queue Dashboard based on FastAPI
- Host: GitHub
- URL: https://github.com/hannes221/rq-dashboard-fast
- Owner: Hannes221
- License: mit
- Created: 2024-01-15T10:56:12.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-01-19T17:25:34.000Z (over 1 year ago)
- Last Synced: 2025-04-04T00:07:16.559Z (about 1 year ago)
- Topics: dashboard, docker, docker-image, fastapi, python, redis, redis-queue, redis-queue-monitor, rq, rq-dashboard
- Language: Python
- Homepage:
- Size: 306 KB
- Stars: 97
- Watchers: 1
- Forks: 11
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# RQ Dashboard FastAPI ðŸ›
`RQ Dashboard FastAPI` is a general purpose, lightweight FastAPI-based web frontend to monitor your RQ queues, jobs, and workers in real-time.
Goal of this package is to ease integration into FastAPI-Applications and provide a Docker Image for convenience.
Featured in Related Projects [Redis Queue Docs](https://github.com/rq/rq)
## Features
- **Real-time monitoring** — live view of queues, jobs, and workers with adaptive auto-refresh
- **Queue card view** — donut charts showing job state breakdown at a glance, toggle between card and table view
- **Job management** — inspect, requeue, and delete jobs; view tracebacks with syntax highlighting; export to CSV/JSON
- **Scheduled & recurring jobs** — first-class support for one-off future jobs (`enqueue_at`/`enqueue_in`) and recurring cron jobs via RQ's native `CronScheduler`
- **Worker monitoring** — live worker status, queue assignments, and job throughput
- **Token-based authentication with access scopes** — issue per-token credentials that restrict visibility to specific queues, hide workers or schedulers, enforce read-only mode, and set a custom dashboard title. Ideal for sharing a scoped view with team members or clients without exposing your full infrastructure
- **Dark mode** — OS-aware with manual toggle, persisted across sessions
- **Mountable or standalone** — embed as a FastAPI sub-application on any existing app, or run directly from the terminal
- **Docker-ready** — official images for linux/amd64 and linux/arm64
## Example Usage
```python
from fastapi import FastAPI
from rq_dashboard_fast import RedisQueueDashboard
import uvicorn
app = FastAPI()
dashboard = RedisQueueDashboard("redis://redis:6379/", "/rq")
app.mount("/rq", dashboard)
if __name__ == "__main__":
uvicorn.run(app, host="0.0.0.0", port=8000)
```
Access the Dashboard at
```
http://127.0.0.1:8000/rq
```
## Installing from PyPi
PyPi: [rq-dashboard-fast](https://pypi.org/project/rq-dashboard-fast/)
```
$ pip install rq-dashboard-fast
```
## Running Standalone
After installing, you can run the dashboard directly from the terminal:
```
$ rq-dashboard-fast
```
This starts the dashboard at `http://localhost:8000/rq` using Redis at `redis://localhost:6379`.
Available options:
```
$ rq-dashboard-fast --help
$ rq-dashboard-fast --redis-url redis://my-redis:6379 --port 9000
$ rq-dashboard-fast --host 127.0.0.1 --prefix /dashboard
```
| Flag | Default | Environment Variable |
|------|---------|---------------------|
| `--redis-url` | `redis://localhost:6379` | `REDIS_URL` |
| `--host` | `0.0.0.0` | `FASTAPI_HOST` |
| `--port` | `8000` | `FASTAPI_PORT` |
| `--prefix` | `/rq` | — |
| `--auth-config` | — | `RQ_DASH_AUTH_CONFIG` |
## Authentication
The dashboard supports opt-in token-based authentication with per-queue access control. Generate a token, create a YAML config file with hashed tokens and queue scopes, and pass it via `--auth-config` or `RQ_DASH_AUTH_CONFIG`. When no config is provided, the dashboard runs with open access as before.
```bash
rq-dashboard-fast generate-token # generate a token + hash pair
rq-dashboard-fast --auth-config auth.yaml # start with auth enabled
```
See the full documentation in [docs/authentication.md](docs/authentication.md).
## Scheduled & Recurring Jobs
The dashboard displays both one-off future-scheduled jobs (via `queue.enqueue_at()` / `queue.enqueue_in()`) and recurring cron jobs (via `CronScheduler`). Each appears in a different part of the UI.
See [docs/scheduling.md](docs/scheduling.md) for a full explanation.
## Running in Docker
1. You can run the RQ Dashboard FastAPI as a Docker container with custom Redis URL:
```
docker run -e REDIS_URL= hannes221/rq-dashboard-fast
```
Access the Dashboard at
```
http://127.0.0.1:8000/rq
```
To change change the port, you can specify the following flag:
```
docker run -e REDIS_URL= -e FASTAPI_PORT= hannes221/rq-dashboard-fast
```
Replace with your desired FastAPI and host port.
2. You can use Docker Compose by creating a docker-compose.yml file:
```yml
services:
dashboard:
image: hannes221/rq-dashboard-fast
ports:
- '8000:8000'
environment:
- REDIS_URL=
```
Then run:
```
docker compose up
```
Access the Dashboard at
```
http://127.0.0.1:8000/rq
```
To change the part update the compose file:
```yml
services:
dashboard:
image: hannes221/rq-dashboard-fast
ports:
- ':'
environment:
- REDIS_URL=
- FASTAPI_PORT=
```
Replace with your desired FastAPI and host port.
Docker Hub: [hannes221/rq-dashboard-fast](https://hub.docker.com/r/hannes221/rq-dashboard-fast)
## Github Repository
Github: [rq-dashboard-fast](https://github.com/Hannes221/rq-dashboard-fast)
```
$ pip install rq-dashboard-fast
```
## Development
### Frontend CSS (UnoCSS)
The dashboard uses [UnoCSS](https://unocss.dev/) with utility classes applied directly in Jinja2 templates. The generated CSS file (`rq_dashboard_fast/static/css/uno.css`) is committed to the repo, so **no Node.js is needed** to run the dashboard — only to modify styles.
```bash
npm install # Install UnoCSS CLI (first time only)
npm run dev:css # Watch mode — rebuilds on template changes
npm run build:css # One-off build
```
UnoCSS scans all `rq_dashboard_fast/templates/**/*.html` files and outputs to `rq_dashboard_fast/static/css/uno.css`. Configuration lives in `uno.config.ts` and includes:
- **Shortcuts** — reusable class groups for buttons (`btn-delete`, `btn-requeue`, etc.), table cells (`th-cell`, `td-cell`), and status badges (`badge-failed`, `badge-started`, etc.)
- **Safelist** — badge classes that are constructed dynamically in JS (`'badge-' + state`) and wouldn't be detected by static scanning
- **Dark mode** — class-based (`darkMode: 'class'`), toggled on `` via a button in the header
After modifying templates or `uno.config.ts`, run `npm run build:css` and commit the updated `uno.css`.
### Additional CSS
`rq_dashboard_fast/static/css/custom.css` contains styles that can't be expressed as utilities: notification toasts (dynamically created by JS) and Pygments dark mode overrides.
## Contributing
If you want to contribute, reach out or create a PR directly.