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.

$ 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:

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 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:

$ 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:

$ 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:

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.