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.

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

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

From container image

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

Terminal window
docker pull ghcr.io/riverqueue/riverui:latest
docker run -p 8080:8080 --env DATABASE_URL ghcr.io/riverqueue/riverui: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

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

opts := &riverui.ServerOpts{
    Client: riverClient,
    DB: pgxPool,
    Logger: slogLogger,
    Prefix: "/riverui", // mount the UI and its APIs under /riverui
    // ...
}
server, err := riverui.NewServer(opts)
if err != nil {
    log.Fatal(err)
}
// Start the server to initialize background processes for caching and periodic queries:
server.Start(ctx)


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


// ... start and run your HTTP server

A complete example can be found in the riverui executable.