River UI is a graphical user interface for the River job queue. It lets users view and manage jobs without having to resort to querying the database or the command line.

The Limits page shows configured River claim-time limit rules and observed job counts by limit metadata key and queue.

For this fork's Chinese documentation, see River 限流扩展中文说明 and 项目说明.

The Chinese documentation index is available at River UI 中文说明.

A live demo of River UI is available to see what it looks like.

A working River database is required for the UI to start up properly. See running River migrations, and make sure a DATABASE_URL is exported to env.

$ go install github.com/riverqueue/river/cmd/river@latest
$ river migrate-up --database-url "$DATABASE_URL"

River UI releases include a set of static binaries for a variety of architectures and operating systems. Use one of these links:

• Linux AMD64
• Linux ARM64
• macOS AMD64
• macOS ARM64

Or fetch a binary with cURL:

$ RIVER_ARCH=arm64 # either 'amd64' or 'arm64'
$ RIVER_OS=darwin  # either 'darwin' or 'linux'
$ curl -L https://github.com/riverqueue/riverui/releases/latest/download/riverui_${RIVER_OS}_${RIVER_ARCH}.gz | gzip -d > riverui
$ chmod +x riverui
$ export DATABASE_URL=...
$ ./riverui

River UI ships container images with each release. Pull and run the latest with:

$ docker pull ghcr.io/riverqueue/riverui:latest
$ docker run -p 8080:8080 --env DATABASE_URL ghcr.io/riverqueue/riverui:latest

See health checks.

Serve River UI under a URL prefix like /ui by setting -prefix (binary) or PATH_PREFIX (Docker). Rules: must start with /, use / for no prefix, and a trailing / is ignored.

Example: ./riverui -prefix=/ui serves the UI at /ui/ and the API at /ui/api/... (and /ui will redirect to /ui/).

Reverse proxies: either preserve the prefix and set -prefix=/ui, or strip the prefix and leave -prefix=/ (don’t do both).

The RIVER_JOB_LIST_HIDE_ARGS_BY_DEFAULT environment variable controls whether, by default, the job list UI shows job arguments. By default job arguments are always shown. If RIVER_JOB_LIST_HIDE_ARGS_BY_DEFAULT=true or RIVER_JOB_LIST_HIDE_ARGS_BY_DEFAULT=1 is set, job args will not be shown in the job list by default.

Individual users may still override this preference using the settings screen in the UI. A user's saved preference takes precedence over any default setting.

The riverui supports HTTP basic authentication to protect access to the UI. To enable it, set the RIVER_BASIC_AUTH_USER and RIVER_BASIC_AUTH_PASS environment variables.

Alternatively, if embedding River UI into another Go app, you can wrap its http.Handler with any custom authentication logic.

The riverui command utilizes the RIVER_LOG_LEVEL environment variable to configure its logging level. The following values are accepted:

• debug
• info (default)
• warn
• error

By default logs are written with the slog.TextHandler key=value format. For JSON output with slog.JSONHandler, set RIVER_LOG_FORMAT=json.

See developing River UI.