Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.risingwave.com/llms.txt

Use this file to discover all available pages before exploring further.

RisingWave Console is a self-hosted service. It stores its own metadata, such as users, cluster connections, database connections, tasks, and settings, in PostgreSQL. It does not store RisingWave user data in this metadata database. Production builds require the signed RisingWave license key at startup. This is the same license key used by the RisingWave database. Provide it with either RW_LICENSE_KEY or RW_LICENSE_KEY_PATH. For details about where to configure the key, see Manage license keys.

​
Choose a deployment target

TargetMetadata PostgreSQLBest for
Docker with -pgbundle imagePostgreSQL runs inside the Console containerLocal evaluation, demos, or a single VM
Docker or binary with external PostgreSQLYou provide PostgreSQLPersistent single-host deployments
Kubernetes with -pgbundle manifestPostgreSQL runs inside the Console podSmall, self-contained Kubernetes tests
Kubernetes with external PostgreSQL manifestYou provide PostgreSQLProduction, OpenShift, and restricted clusters
For persistent deployments, use a strong RCONSOLE_ROOT_PASSWORD, protect the Console endpoint with your network controls, and prefer external PostgreSQL for durable Console metadata.

​
Key configuration

SettingRequiredDescription
RW_LICENSE_KEYYes, unless RW_LICENSE_KEY_PATH is setSigned RisingWave license key used for Console startup verification.
RW_LICENSE_KEY_PATHYes, unless RW_LICENSE_KEY is setPath to a mounted file containing the signed license key. Recommended for Docker and Kubernetes.
RCONSOLE_ROOT_PASSWORDRecommendedInitial password for the root user. If unset, the default password is root.
RCONSOLE_SERVER_PG_DSNRequired for non-pgbundle deploymentsPostgreSQL DSN for Console metadata, for example postgres://user:password@postgres.example:5432/rconsole.
RCONSOLE_SERVER_PORTOptionalHTTP port for Console. The default is 8020.
RCONSOLE_SERVER_METRICSPORTOptionalPrometheus metrics port for Console itself. The default is 9020.
RCONSOLE_NOINTERNETOptionalSet to true when Console should not download risectl or Helm charts from the public internet.
RCONSOLE_RISECTLDIROptionalDirectory where Console stores or reads risectl binaries.
RCONSOLE_HELM_CHART_DIROptionalDirectory where Console stores or reads Helm chart archives for air-gapped installs.

​
Docker quick start

Use the bundled PostgreSQL image for the fastest setup: 
export RW_LICENSE_KEY="<your-signed-license-token>"

docker run -d -p 8020:8020 --name risingwave-console \
  -e RCONSOLE_ROOT_PASSWORD=your_secure_password \
  -e RW_LICENSE_KEY="$RW_LICENSE_KEY" \
  -v risingwave-console-data:/var/lib/postgresql \
  risingwavelabs/risingwave-console:latest-pgbundle
Open http://localhost:8020 and sign in as root with the password you set in RCONSOLE_ROOT_PASSWORD. If you prefer mounted files for secrets: 
docker run -d -p 8020:8020 --name risingwave-console \
  -e RCONSOLE_ROOT_PASSWORD=your_secure_password \
  -e RW_LICENSE_KEY_PATH=/etc/rconsole/license.jwt \
  -v "$PWD/license.jwt:/etc/rconsole/license.jwt:ro" \
  -v risingwave-console-data:/var/lib/postgresql \
  risingwavelabs/risingwave-console:latest-pgbundle
For a throwaway local test, remove the volume and add --rm. Console metadata is deleted when the container is removed.

​
Docker with external PostgreSQL

Use the standard image when PostgreSQL is managed outside the Console container: 
services:
  risingwave-console:
    image: risingwavelabs/risingwave-console:latest
    ports:
      - "8020:8020"
    environment:
      RCONSOLE_ROOT_PASSWORD: your_secure_password
      RCONSOLE_SERVER_PG_DSN: postgres://rconsole_user:rconsole_password@postgres:5432/rconsole
      RW_LICENSE_KEY_PATH: /etc/rconsole/license.jwt
    volumes:
      - ./license.jwt:/etc/rconsole/license.jwt:ro
Start it with: 
docker compose up -d
The PostgreSQL user in RCONSOLE_SERVER_PG_DSN must be able to create and migrate Console metadata tables.

​
Kubernetes deployment

Console provides two starter manifests:
  • deploy/kubernetes/pgbundle/console.yaml: runs the -pgbundle image. This is convenient for testing, but the bundled PostgreSQL metadata is not durable across pod rescheduling.
  • deploy/kubernetes/external-pg/console.yaml: runs the standard image with external PostgreSQL. This is the production path and also works with OpenShift restricted security settings.
Both manifests create:
  • the risingwave-console namespace,
  • a ServiceAccount,
  • RBAC for Console operations and environment-managed resources,
  • a StatefulSet,
  • a Service that exposes Console on NodePort 30020 and Console metrics on NodePort 30090.

​
Kubernetes startup license

Store the RisingWave license key in a Kubernetes Secret: 
apiVersion: v1
kind: Secret
metadata:
  name: risingwave-console-license
  namespace: risingwave-console
type: Opaque
stringData:
  license.jwt: <your-signed-license-token>
Reference it from the console container: 
- name: RW_LICENSE_KEY
  valueFrom:
    secretKeyRef:
      name: risingwave-console-license
      key: license.jwt
The external PostgreSQL manifest already includes a risingwave-console-config Secret for pg-dsn, root-password, and license.jwt. Replace the placeholder values before applying it.

​
Apply a starter manifest

For a Kubernetes test deployment: 
kubectl apply -f deploy/kubernetes/pgbundle/console.yaml
For production or OpenShift: 
kubectl apply -f deploy/kubernetes/external-pg/console.yaml
Access the UI at http://<any-node>:30020, or replace the Service with your preferred ClusterIP, LoadBalancer, or Ingress setup.
The starter manifests include RBAC that lets Console install cert-manager, the RisingWave Operator, and environment-scoped resources. If those components are managed by another platform team, remove the cluster-installer RBAC and use imported resources instead.

​
Binary deployment

Use the binary when you want to run Console directly on a host and manage PostgreSQL separately: 
RW_LICENSE_KEY_PATH=/etc/rconsole/license.jwt \
RCONSOLE_SERVER_PG_DSN="postgres://rconsole_user:rconsole_password@postgres.example:5432/rconsole" \
RCONSOLE_ROOT_PASSWORD="your_secure_password" \
./risingwave-console
Make sure the process can read the license file and reach the PostgreSQL host.

​
Verify the installation

  1. Check the process or container logs.
  2. Open the UI:
    • Docker or binary: http://localhost:8020, unless you changed the port.
    • Kubernetes NodePort starter manifest: http://<any-node>:30020.
  3. Sign in as root.
  4. Confirm that the home page loads and the sidebar shows Clusters, Environments, Metrics Store, SQL Console, and Settings.

​
Troubleshooting startup

SymptomCheck
Console exits with a missing license errorSet RW_LICENSE_KEY or RW_LICENSE_KEY_PATH. If using a file, confirm the path inside the container or pod.
Console reports that the license does not enable premiumUse a signed RisingWave license key with the premium feature enabled.
PostgreSQL connection failsVerify RCONSOLE_SERVER_PG_DSN, network reachability, TLS requirements, and database user permissions.
Port 8020 is already in useChange the host port mapping or set RCONSOLE_SERVER_PORT.
Kubernetes pod starts but the UI is unreachableCheck the Service type, NodePort or Ingress configuration, and network policies.
After installation, either connect an existing RisingWave cluster or create a Kubernetes environment.