> ## 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.

# Docker Compose

> This topic describes how to start RisingWave using Docker Compose on a single machine. With this option, data is persisted in your preferred storage service, and observability is enabled for enhanced monitoring and analysis.

In this option, RisingWave functions as an all-in-one service. All components of RisingWave, including Serving and Streaming Nodes, Meta Node, and Compactor Node, are put into a single process. They are executed in different threads, eliminating the need to start each component as a separate process.

However, please be aware that certain critical features, such as failover and resource management, are not implemented in this mode. Therefore, this option is not recommended for production deployments. For production deployments, please consider [RisingWave Cloud](/deploy/risingwave-cloud), [Kubernetes with Helm](/deploy/risingwave-k8s-helm), or [Kubernetes with Operator](/deploy/risingwave-kubernetes).

This option uses a pre-defined Docker Compose configuration file to set up a RisingWave cluster.

The cluster also incorporates these third-party components:

* Grafana
* PostgreSQL/MySQL
* MinIO
* Prometheus

## Download the source file

As a prerequisite, you need to install [Docker Desktop](https://docs.docker.com/get-docker/) in your environment. Ensure that it is running before launching the cluster.

Then, clone the [risingwave](https://github.com/risingwavelabs/risingwave) repository.

```bash theme={null}
git clone https://github.com/risingwavelabs/risingwave.git
```

Open the repository in a terminal and run the following command to navigate to the `docker` directory.

```bash theme={null}
cd docker
```

## Customize your cluster configuration

You can customize your RisingWave deployment configuration by changing the options for the state store and meta store.

### Customize state store

For state store, RisingWave supports using these systems or services, and for each of the options, we have a [Docker Compose configuration file](https://github.com/risingwavelabs/risingwave/tree/main/docker) that you can use after the necessary configurations.

* [MinIO](#minio)
* [S3 or S3-compatible storage](#s3-or-s3-compatible-storage)
* [Google Cloud Storage, Alibaba Cloud OSS, or Azure Blob Storage](#google-cloud-storage-alibaba-cloud-oss-or-azure-blob-storage)
* [HDFS](#hdfs)
* [Huawei Cloud OBS](#huawei-cloud-obs)

#### MinIO

This is the default option. To start a standalone RisingWave cluster with MinIO as the state store, run the following command:

```bash theme={null}
docker compose up -d
```

<Tip>
  **COMMAND NOT FOUND?**

  The default command-line syntax in Compose V2 starts with `docker compose`. See details in the [Docker docs](https://docs.docker.com/compose/migrate/#what-are-the-differences-between-compose-v1-and-compose-v2).

  If you're using Compose V1, use `docker-compose` instead.
</Tip>

<Warning>
  **Memory is crucial for RisingWave.**

  Inappropriate memory configuration may lead to OOM (out-of-memory) errors or poor performance. Before deploying Docker Compose, ensure that the correct memory settings are configured in the `docker-compose.yaml` file. Here are examples of some typical settings.

  | Memory for RisingWave container (`resource.limits.memory`) | 8 GiB   | 14 GiB  | 28 GiB   | 58 GiB   |
  | :--------------------------------------------------------- | :------ | :------ | :------- | :------- |
  | `compute-opts.total-memory-bytes`                          | 6 GiB   | 10 GiB  | 20 GiB   | 46 GiB   |
  | `frontend-opts.frontend-total-memory-bytes`                | 1 GiB   | 2 GiB   | 4 GiB    | 6 GiB    |
  | `compactor-opts.compactor-total-memory-bytes`              | 1 GiB   | 2 GiB   | 4 GiB    | 6 GiB    |
  | `compute-opts.memory-manager-target-bytes`                 | 5.6 GiB | 9.8 GiB | 20.8 GiB | 44.8 GiB |
</Warning>

<Accordion title="I'd like to start RisingWave components separately in a multi-node cluster.">
  You can also run a multi-node cluster, with each component (Serving, Streaming, Meta, and Compactor Nodes) running as a separate process.

  By default, this mode uses MinIO as the state store of RisingWave.

  To start a multi-node RisingWave cluster with MinIO as the state store, run the following command:

  ```bash theme={null}
  docker compose -f docker-compose-distributed.yml up
  ```
</Accordion>

#### S3 or S3-compatible storage

To use S3 as the state store, configure your AWS credential information in `/docker/aws.env`.

To use S3-compatible storage options like Tencent Cloud COS, you need to configure the endpoint via the `RW_S3_ENDPOINT` parameter in `/docker/aws.env`. Don't include the bucket name in the endpoint.

In `docker-compose-with-s3.yml`, specify the bucket name via the `hummock+s3` parameter.

```bash theme={null}
- "hummock+s3://<bucket-name>"
```

#### Google Cloud Storage, Alibaba Cloud OSS, or Azure Blob Storage

Configure the credentials for the cloud service you want to use in `/docker/multiple_object_storage.env`.

In the corresponding `docker-compose-with-service_name.yml` file (for example, `docker-compose-with-gcs.yml` for Google Cloud Storage), specify the bucket name via the `hummock+<service_name>` parameter.

```bash theme={null}
 - "hummock+<service_name>://<bucket-name>"
```

#### HDFS

Fill in your image name, cluster name (or namenode), and data directory

Mount your `HADOOP_HOME` to the volume `<$HADOOP_HOME>:/opt/hadoop/`, see [docker-compose-with-hdfs.yml](https://github.com/risingwavelabs/risingwave/blob/main/docker/docker-compose-with-hdfs.yml) for more information.

#### Huawei Cloud OBS

To use Huawei Cloud OBS as the state store, you need to configure your OBS credential information in the `multiple_object_storage.env` file. Uncomment and set the following environment variables: `OBS_ENDPOINT`, `OBS_ACCESS_KEY_ID`, and `OBS_SECRET_ACCESS_KEY`. Don't include the bucket name in the endpoint.

In the `docker-compose-with-obs.yml` file, specify the bucket name via the `hummock+obs` parameter. Replace `<bucket-name>` with the name of your OBS bucket.

```bash theme={null}
--state-store hummock+obs://<bucket-name>
```

### Customize meta store

For meta store, RisingWave uses [postgresql](#postgresql) as the default meta store backend and also supports the following meta store backends:

* [MySQL or MySQL-compatible storage](#mysql-or-mysql-compatible-storage)
* [SQLite](#sqlite)

To customize the meta store backend, you need to configure the following settings.

* `--backend`: The meta store backend you want to use.
* `--sql-endpoint`: The target SQL backend endpoint.
* Some parameters that required for specified backends.

You can read the specified guide for setting each backend below for more details.

#### PostgreSQL

* `--backend`: Set to `postgres`.
* `--sql-endpoint`: Configure in format `{host}:{port}`.
* Three additional parameters are required:
  * `--sql-username`: Username of SQL backend.
  * `--sql-password`: Password of SQL backend.
  * `--sql-database`: Database of SQL backend.

#### SQLite

* `--backend`: Set to `sqlite`.
* `--sql-endpoint`: Should be the file path.

We have a Docker Compose configuration file that you can use after the necessary configurations: [docker-compose-with-sqlite.yml](https://github.com/risingwavelabs/risingwave/blob/main/docker/docker-compose-with-sqlite.yml). In this file, meta will mount a volume for SQLite db file, which means the SQLite meta storage backend requires singleton meta component.

#### MySQL or MySQL-compatible storage

* `--backend`: Set to `mysql`.
* `--sql-endpoint`: Configure in format `{host}:{port}`. In [docker-compose-with-sqlite.yml](https://github.com/risingwavelabs/risingwave/blob/main/docker/docker-compose-with-sqlite.yml), specify the storage backend via `mysql` parameter.

```
--sql-endpoint mysql://<user>:<password>@<host>:<port>/<db>
```

* Three additional parameters are required:
  * `--sql-username`: Username of SQL backend.
  * `--sql-password`: Password of SQL backend.
  * `--sql-database`: Database of SQL backend.

## Start a RisingWave cluster

You can now run the following command to start a RisingWave cluster:

```bash theme={null}
docker compose -f docker-compose-with-storage_backend_name.yml up
```

Remember to replace the `docker-compose-with-storage_backend_name.yml` with the full file name of the corresponding configuration file.

## Connect to RisingWave

After RisingWave is up and running, you need to connect to it via the Postgres interactive terminal `psql` so that you can issue queries to RisingWave and see the query results. If you don't have `psql` installed, [install psql](/deploy/install-psql-without-postgresql) first.

```bash theme={null}
psql -h localhost -p 4566 -d dev -U root
```

**Alternative: Use RisingWave Console**

You can also connect to and manage your RisingWave cluster using the [RisingWave Console](/web-ui/introduction), which provides a web-based interface for cluster monitoring, SQL queries, and operational tasks.

Notes about the `psql` options:

* The `-h` option is used to specify the hostname or IP address of the PostgreSQL server to connect to.
* The `-p` option is used to specify the port number that the server is listening on.
* The `-d` option is used to specify the name of the database to connect to.
* The `-U` option is used to specify the name of the database user to connect as.
* By default, the PostgreSQL server uses the `root` user account to authenticate connections to the `dev` database. Note that this user account does not require a password to connect.

## Manage your RisingWave cluster

When the cluster is running, you can monitor the status of RisingWave and the additional components and make adjustments when necessary.

* **RisingWave Dashboard**

Access the RisingWave Dashboard at [http://127.0.0.1:5691/](http://127.0.0.1:5691/). RisingWave Dashboard displays an overview of the cluster, as well as sources, sinks, tables, materialized views, and indexes available on the cluster.

* **Grafana**

Access Grafana at [http://127.0.0.1:3001/](http://127.0.0.1:3001/) and search for `risingwave_dev_dashboard`. In this dashboard, you can view internal metrics such as node count, memory consumption, throughput, and latencies. You can use these metrics to troubleshoot and optimize the cluster performance.

<Note>
  We recommend `risingwave_dev_dashboard` as the primary dashboard. `risingwave_dashboard` is also available.
</Note>

* **MinIO**

Access the MinIO instance at [http://127.0.0.1:9400/](http://127.0.0.1:9400/). Use the following credentials to log in.

* User name: `hummockadmin`
* Password: `hummockadmin`
* **Prometheus**

Access Prometheus at [http://127.0.0.1:9500/](http://127.0.0.1:9500/). No credentials are needed. You can use Prometheus for real-time alerting.

### CI and testing

The RisingWave CI pipeline uses a separate Docker Compose file at `ci/docker-compose.yml`, which pre-starts all external services. Tests then run with `risedev` configured in `user-managed` mode, pointing to these pre-started services.

For local testing that mimics CI, see `risedev.yml` template section for `user-managed: true` examples.

## Common issues

One of the common issues you may encounter is insufficient storage space. For example:

```bash theme={null}
Error { code: "XMinioStorageFull", message: "Storage backend has reached its minimum free drive threshold. Please delete a few objects to proceed." }
```

This issue typically occurs on macOS when using Docker Desktop. Docker Desktop runs within the macOS Hypervisor, where all the data, including logs, images, and volumes, is stored. The macOS Hypervisor has a default limit on disk capacity. If you encounter this error, you can resolve it by cleaning up unused containers or images. Another option is to increase the disk image size limit by following these steps: Click on the Docker Desktop icon in the menu bar, then go to **Preferences** > **Resources** > **Advanced**, and adjust the slider for disk image size to allocate more space for Docker images. If you are using a different platform, please ensure sufficient space is available on the local disk.

<head>
  <script type="application/ld+json">
    {`
          {
            "@context": "https://schema.org",
            "@type": "HowTo",
            "name": "How to deploy RisingWave with Docker Compose",
            "description": "Deploy a RisingWave cluster using Docker Compose with persistent storage and observability. Includes state store and meta store configuration options.",
            "step": [
              {
                "@type": "HowToStep",
                "name": "Download the source file",
                "text": "Install Docker Desktop, then clone the RisingWave repository with 'git clone https://github.com/risingwavelabs/risingwave.git' and navigate to the docker directory."
              },
              {
                "@type": "HowToStep",
                "name": "Configure state store and meta store",
                "text": "Choose your state store (MinIO, S3, GCS, Azure Blob, HDFS) and meta store (PostgreSQL, MySQL, SQLite) by selecting the appropriate Docker Compose configuration file."
              },
              {
                "@type": "HowToStep",
                "name": "Start the RisingWave cluster",
                "text": "Run 'docker compose up -d' to start the cluster with the default MinIO configuration, or specify a custom configuration file with the -f flag."
              },
              {
                "@type": "HowToStep",
                "name": "Connect to RisingWave",
                "text": "Connect to RisingWave using psql: psql -h localhost -p 4566 -d dev -U root"
              }
            ]
          }
          `}
  </script>
</head>