This guide provides instructions for installing and setting up RisingWave Console. RisingWave Console requires a PostgreSQL database to store its metadata (like cluster connection details). You can use a bundled PostgreSQL for quick setup or connect to your own existing instance.

​
Key configuration variables

Before you begin, be aware of these key environment variables that RisingWave Console uses:
  • RCONSOLE_PORT: (Optional) Specifies the port on which the RisingWave Console server will listen. Defaults to 8020.
  • RCONSOLE_PG_DSN: (Required for binary and Docker Compose with external PG) The PostgreSQL connection string for RisingWave Console’s metadata database.
    • Format: postgres://<user>:<password>@<host>:<port>/<database_name>
    • It’s important to note that this database is used by RisingWave Console to store its own operational data and does not store your RisingWave cluster’s user data.
  • RCONSOLE_ROOT_PASSWORD: (Optional) Sets the initial password for the root user in the RisingWave Console UI. If not set, it defaults to root. It’s recommended to set this for any persistent deployment.
  • RCONSOLE_RISECTLDIR: (Optional) May be used by RisingWave Console if it needs to locate risectl resources for executing commands against your RisingWave cluster. The default behavior usually suffices.

​
System requirements

  • Memory: Minimum 512MB RAM (1GB recommended)
  • Storage: At least 1GB free disk space
  • Architecture: x86_64 and ARM64 are supported
  • Network: Port 8020 (or your custom port) must be accessible

​
Option 1: Quick setup with docker (bundled PostgreSQL)

This is the fastest way to try RisingWave Console. The risingwavelabs/risingwave-console:vX.Y.Z-pgbundle image includes a PostgreSQL server and is hosted on Docker Hub. Replace vX.Y.Z with the desired RisingWave Console version (for example, v0.4.0).
Security Note: For production deployments, always set a strong RCONSOLE_ROOT_PASSWORD and ensure the console is not exposed to public networks without proper authentication.
  • Ephemeral storage (for testing only) All RisingWave Console metadata will be lost if the container is removed. 
    docker run --rm -p 8020:8020 --name risingwave-console risingwavelabs/risingwave-console:vX.Y.Z-pgbundle
    To set a custom root password: 
    docker run --rm -p 8020:8020 -e RCONSOLE_ROOT_PASSWORD=your_secure_password --name risingwave-console risingwavelabs/risingwave-console:vX.Y.Z-pgbundle
  • Persistent storage (recommended for standalone Docker) RisingWave Console metadata is stored in a Docker volume (risingwave-console-data), ensuring data persists across container restarts or recreations. 
    docker run -d -p 8020:8020 --name risingwave-console \
  -e RCONSOLE_ROOT_PASSWORD=your_secure_password \
  -v risingwave-console-data:/var/lib/postgresql \
  risingwavelabs/risingwave-console:vX.Y.Z-pgbundle

​
Option 2: Setup with binary (requires external PostgreSQL)

This method uses a standalone RisingWave Console binary and requires you to have a separate, running PostgreSQL database.
  1. Download and install the latest RisingWave Console binary: 
    curl https://risingwave-console-release.s3.ap-southeast-1.amazonaws.com/download.sh | sh
  2. Ensure your PostgreSQL database is accessible and set the RCONSOLE_PG_DSN environment variable. Then, run RisingWave Console: 
    RCONSOLE_PG_DSN="postgres://your_user:your_pass@your_pg_host:5432/dbname" \
RCONSOLE_ROOT_PASSWORD="your_secure_password" \
./risingwave-console
    (Adjust RCONSOLE_PG_DSN and RCONSOLE_ROOT_PASSWORD accordingly.)
This method uses Docker Compose to run RisingWave Console and allows you to easily manage it alongside your own PostgreSQL instance (either also as a Docker container or an external one).
  1. Create a docker-compose.yaml file: 
    version: "3.9"
services:
  risingwave-console:
    image: risingwavelabs/risingwave-console:vX.Y.Z # Use the image without -pgbundle
    ports:
      - "8020:8020" # Or your RCONSOLE_PORT
    environment:
      RCONSOLE_PORT: 8020 # Optional, if different from default
      RCONSOLE_PG_DSN: postgres://postgres_user:postgres_password@db_host:5432/risingwave_console_metadata_db # IMPORTANT: Point to your PG
      RCONSOLE_ROOT_PASSWORD: your_secure_password
      # RCONSOLE_RISECTLDIR: /path/if/needed
    depends_on:
      - db # Only if PostgreSQL is also managed by this Docker Compose file

  # Example: If running PostgreSQL in Docker Compose as well
  db:
    image: "postgres:15" # Or your preferred version
    ports:
      - "5432:5432" # Expose if needed externally, otherwise RisingWave Console connects via Docker network
    environment:
      POSTGRES_USER: postgres_user
      POSTGRES_PASSWORD: postgres_password
      POSTGRES_DB: risingwave_console_metadata_db
    volumes:
      - postgres_risingwave_console_data:/var/lib/postgresql/data

volumes:
  postgres_risingwave_console_data: # For the PostgreSQL container
    Note:
    • Replace vX.Y.Z with the specific RisingWave Console version (for example, v0.4.0).
    • Adjust RCONSOLE_PG_DSN to point to your PostgreSQL instance. If db is a service in the same Docker Compose, you can use db_host: db.
    • Update PostgreSQL credentials and database name.
  2. Start RisingWave Console: 
    docker compose up -d

​
Verifying the installation

After starting RisingWave Console, check its logs to ensure it started without errors:
  • If using Docker/Docker Compose: docker logs risingwave-console (or your service name).
  • If using binary: Observe the terminal output.

​
Finding the latest version

To find the latest available version of RisingWave Console:

​
Troubleshooting common issues

  • Port already in use: If port 8020 is occupied, change RCONSOLE_PORT to an available port (e.g., 8021)
  • Connection refused: Ensure your PostgreSQL database is running and accessible
  • Permission denied: Check that the user has appropriate permissions to access the PostgreSQL database
  • Container fails to start: Verify that the Docker image name and version are correct

​
Initial login and dashboard overview

  1. Access RisingWave Console UI: Open your web browser and navigate to http://localhost:8020 (or the host/port you configured).
  2. Login:
    • Username: root
    • Password: The password you set via RCONSOLE_ROOT_PASSWORD, or root if not set.
  3. Dashboard: Upon successful login, you’ll see the RisingWave Console dashboard. This is your main entry point to:
    • Manage Clusters: For connecting to your RisingWave instances.
    • Use the SQL Console: For querying your RisingWave data.
    • Access links to external resources and documentation.
You are now ready to Connect to your RisingWave clusters!