Skip to content
River Docs

Running the River web UI

River includes a graphical user interface, which lets users view and manage jobs without having to resort to manually querying the database, or falling back to the command line.

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

Pro vs OSS River UI

River UI is available in two flavors:

  • The base riverui package is the fully open-source version of River UI.
  • The riverproui variant leverages Pro-specific APIs and functionality, requiring the riverqueue.com/riverpro module via a River Pro subscription.

Both variants are available as Go modules for self-compilation or integration into other Go applications. Each is also available as a Docker image. Published binaries are available only for the open-source version.

Installation

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.

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

Optional Basic Authentication

By default, the River web UI is publicly accessible. To enable basic HTTP authentication, set the environment variables:

Terminal window
export RIVER_BASIC_AUTH_USER=<your-username>
export RIVER_BASIC_AUTH_PASS=<your-password>

Alternatively, embed the UI into your own application and handle authentication however you'd like.

From source

River UI is primarily distributed as a packaged Go module and can be installed with go install:

Terminal window
go install riverqueue.com/riverui/cmd/riverui@latest
riverui

For Pro customers, use the riverproui package instead of riverui:

Terminal window
go install riverqueue.com/riverui/riverproui/cmd/riverproui@latest
riverproui

From binary

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

Or fetch a binary with cURL:

Terminal window
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
./riverui

These binaries are only available for the open-source version of River UI. Pro customers should use the container image or embed the Go handler instead.

From container image

River UI ships container images with each release, both open-source and Pro variants. Pull and run the latest OSS / non-Pro variant with:

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

For Pro customers, use the riverqueue.com/riverproui image instead of riverui. This requires first logging in to the riverqueue.com Docker registry with a River Pro license key (see Getting started with River Pro):

Terminal window
# assuming RIVER_PRO_SECRET is set to a valid River Pro license key:
echo $RIVER_PRO_SECRET | docker login riverqueue.com -u river --password-stdin
docker pull riverqueue.com/riverproui:latest
docker run -p 8080:8080 --env DATABASE_URL riverqueue.com/riverproui:latest

Embedding into another Go app

River UI can also be embedded into an existing Go app as an http.Handler. This is useful for adding a UI to an existing service without needing to run a separate process or for placing the UI behind a custom authentication setup.

Add the module to your project:

Terminal window
go get -u riverqueue.com/riverui@latest
# or, for Pro customers:
go get -u riverqueue.com/riverui/riverproui@latest

Next, create a new riverui.Handler, start it, and mount it to your HTTP mux:

endpoints := riverui.NewEndpoints(riverClient, nil)
// or, for Pro customers:
endpoints = riverproui.NewEndpoints(riverProClient, nil)


opts := &riverui.HandlerOpts{
    DB: pgxPool,
    Endpoints: endpoints,
    Logger: slogLogger,
    Prefix: "/riverui", // mount the UI and its APIs under /riverui or another path
    // ...
}
handler, err := riverui.NewHandler(opts)
if err != nil {
    log.Fatal(err)
}
// Start the handler to initialize background processes for caching and periodic queries:
handler.Start(ctx)


mux := http.NewServeMux()
mux.Handle("/riverui", handler)


// ... start and run your HTTP server

A complete example can be found in the riverui executable.