Installation and setup

Step-by-step guide to install and set up RisingWave Console after obtaining the required image or binary from RisingWave Labs.

This guide provides instructions for installing and setting up RisingWave Console after you obtain the required image or binary from RisingWave Labs. To request access to RisingWave Console and the corresponding installation artifacts, contact [e-mail].

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_SERVER_PORT: (Optional) Specifies the port on which the RisingWave Console server will listen. Defaults to 8020.
• RCONSOLE_SERVER_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 after you receive a bundled image from RisingWave Labs. The bundled image includes a PostgreSQL server. Replace <console-image>:<version>-pgbundle with the image reference provided to you.

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 <console-image>:<version>-pgbundle
  

  To set a custom root password:

  docker run --rm -p 8020:8020 -e RCONSOLE_ROOT_PASSWORD=your_secure_password --name risingwave-console <console-image>:<version>-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 \
    <console-image>:<version>-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. Obtain the RisingWave Console binary package from RisingWave Labs and extract it on your target host.
2. Ensure your PostgreSQL database is accessible and set the RCONSOLE_SERVER_PG_DSN environment variable. Then, run RisingWave Console:
   RCONSOLE_SERVER_PG_DSN="postgres://your_user:your_pass@your_pg_host:5432/dbname" \
   RCONSOLE_ROOT_PASSWORD="your_secure_password" \
   ./risingwave-console
   
   
   (Adjust RCONSOLE_SERVER_PG_DSN and RCONSOLE_ROOT_PASSWORD accordingly.)

Option 3: Recommended setup (docker compose with external PostgreSQL)

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: <console-image>:<version> # Use the image reference provided by RisingWave Labs
       ports:
         - "8020:8020" # Or your RCONSOLE_SERVER_PORT
       environment:
         RCONSOLE_SERVER_PORT: 8020 # Optional, if different from default
         RCONSOLE_SERVER_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 <console-image>:<version> with the image reference provided by RisingWave Labs.
   • Adjust RCONSOLE_SERVER_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.

Getting the correct version

For the correct RisingWave Console image, binary package, and version compatibility guidance, contact RisingWave Labs at [e-mail].

Troubleshooting common issues

• Port already in use: If port 8020 is occupied, change RCONSOLE_SERVER_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 you are using the correct image reference and version provided by RisingWave Labs

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!