docs: Clarify the docs (#42)

paradedb · Oct 2, 2024 · bc562a6 · bc562a6
1 parent 1a95369
commit bc562a6
Show file tree

Hide file tree

Showing 3 changed files with 52 additions and 15 deletions.
diff --git a/README.md b/README.md
@@ -26,13 +26,15 @@
 
 # ParadeDB Helm Chart
 
-This repository contains the Helm chart for deploying and managing [ParadeDB](https://github.com/paradedb/paradedb) on Kubernetes via [CloudNativePG](https://cloudnative-pg.io/).
+The [ParadeDB](https://github.com/paradedb/paradedb) Helm Chart is based on the official [CloudNativePG Helm Chart](https://cloudnative-pg.io/). CloudNativePG is a Kubernetes operator that manages the full lifecycle of a highly available PostgreSQL database cluster with a primary/standby architecture using Postgres streaming replication.
 
-Kubernetes, and specifically the CloudNativePG operator, is the recommended approach for deploying ParadeDB in production. ParadeDB also provides a [Docker image](https://hub.docker.com/r/paradedb/paradedb) and [prebuilt binaries](https://github.com/paradedb/paradedb/releases) for Debian, Ubuntu and Red Hat Enterprise Linux.
+Kubernetes, and specifically the CloudNativePG operator, is the recommended approach for deploying ParadeDB in production, with high availability. ParadeDB also provides a [Docker image](https://hub.docker.com/r/paradedb/paradedb) and [prebuilt binaries](https://github.com/paradedb/paradedb/releases) for Debian, Ubuntu and Red Hat Enterprise Linux.
+
+The chart is also available on [ArtifactHub](https://artifacthub.io/packages/helm/paradedb/paradedb).
 
 ## Getting Started
 
-First, install [Helm](https://helm.sh/docs/intro/install/). The following steps assume you have a Kubernetes cluster running v1.25+. If you are testing locally, we recommend using [Minikube](https://minikube.sigs.k8s.io/docs/start/?arch=%2Fmacos%2Farm64%2Fstable%2Fbinary+download).
+First, install [Helm](https://helm.sh/docs/intro/install/). The following steps assume you have a Kubernetes cluster running v1.25+. If you are testing locally, we recommend using [Minikube](https://minikube.sigs.k8s.io/docs/start/).
 
 ### Installing the CloudNativePG Operator
 
@@ -60,9 +62,9 @@ cluster:
     size: 256Mi
 ```
 
-You can refer to the other examples in the [`charts/paradedb/examples`](https://github.com/paradedb/charts/tree/main/charts/paradedb/examples) directory.
+Then, launch the ParadeDB cluster.
 
-```console
+```bash
 helm repo add paradedb https://paradedb.github.io/charts
 helm upgrade --install paradedb \
 --namespace paradedb-database \
@@ -71,7 +73,23 @@ helm upgrade --install paradedb \
 paradedb/paradedb
 ```
 
-Refer to the [CloudNativePG Cluster Chart documentation](charts/paradedb/README.md) for advanced configuration options.
+If `--values values.yaml` is omitted, the default values will be used. For additional configuration options for the `values.yaml` file, please refer to the [ParadeDB Helm Chart documentation](https://artifacthub.io/packages/helm/paradedb/paradedb#values). For advanced cluster configuration options, please refer to the [CloudNativePG Cluster Chart documentation](charts/paradedb/README.md).
+
+A more detailed guide on launching the cluster can be found in the [Getting Started docs](<./charts/paradedb/docs/Getting Started.md>). To get started with ParadeDB, we suggest you follow the [quickstart guide](/documentation/getting-started/quickstart).
+
+### Connecting to a ParadeDB CNPG Cluster
+
+The command to connect to the primary instance of the cluster will be printed in your terminal. If you do not modify any settings, it will be:
+
+```bash
+kubectl --namespace paradedb-database exec --stdin --tty services/paradedb-rw -- bash
+```
+
+This will launch a shell inside the instance. You can connect via `psql` with:
+
+```bash
+psql -d paradedb
+```
 
 ## License
 

diff --git a/charts/paradedb/README.md b/charts/paradedb/README.md
@@ -1,12 +1,16 @@
 # ParadeDB CloudNativePG Cluster
 
-This README documents the Helm chart for deploying and managing [ParadeDB](https://github.com/paradedb/paradedb) on Kubernetes via [CloudNativePG](https://cloudnative-pg.io/), including advanced settings.
+The [ParadeDB](https://github.com/paradedb/paradedb) Helm Chart is based on the official [CloudNativePG Helm Chart](https://cloudnative-pg.io/). CloudNativePG is a Kubernetes operator that manages the full lifecycle of a highly available PostgreSQL database cluster with a primary/standby architecture using Postgres streaming replication.
 
-Kubernetes, and specifically the CloudNativePG operator, is the recommended approach for deploying ParadeDB in production. ParadeDB also provides a [Docker image](https://hub.docker.com/r/paradedb/paradedb) and [prebuilt binaries](https://github.com/paradedb/paradedb/releases) for Debian, Ubuntu and Red Hat Enterprise Linux.
+Kubernetes, and specifically the CloudNativePG operator, is the recommended approach for deploying ParadeDB in production, with high availability. ParadeDB also provides a [Docker image](https://hub.docker.com/r/paradedb/paradedb) and [prebuilt binaries](https://github.com/paradedb/paradedb/releases) for Debian, Ubuntu and Red Hat Enterprise Linux.
+
+The chart is also available on [ArtifactHub](https://artifacthub.io/packages/helm/paradedb/paradedb).
 
 ## Getting Started
 
-### Installing the Operator
+First, install [Helm](https://helm.sh/docs/intro/install/). The following steps assume you have a Kubernetes cluster running v1.25+. If you are testing locally, we recommend using [Minikube](https://minikube.sigs.k8s.io/docs/start/).
+
+### Installing the CloudNativePG Operator
 
 Skip this step if the CNPG operator is already installed in your cluster.
 
@@ -32,9 +36,9 @@ cluster:
     size: 256Mi
 ```
 
-You can refer to the other examples in the [`charts/paradedb/examples`](https://github.com/paradedb/charts/tree/main/charts/paradedb/examples) directory.
+Then, launch the ParadeDB cluster.
 
-```console
+```bash
 helm repo add paradedb https://paradedb.github.io/charts
 helm upgrade --install paradedb \
 --namespace paradedb-database \
@@ -43,7 +47,23 @@ helm upgrade --install paradedb \
 paradedb/paradedb
 ```
 
-A more detailed guide can be found in the [Getting Started docs](<./docs/Getting Started.md>).
+If `--values values.yaml` is omitted, the default values will be used. For additional configuration options for the `values.yaml` file, please refer to the [ParadeDB Helm Chart documentation](https://artifacthub.io/packages/helm/paradedb/paradedb#values). For advanced cluster configuration options, please refer to the [CloudNativePG Cluster Chart documentation](charts/paradedb/README.md).
+
+A more detailed guide on launching the cluster can be found in the [Getting Started docs](<./docs/Getting Started.md>). To get started with ParadeDB, we suggest you follow the [quickstart guide](/documentation/getting-started/quickstart).
+
+### Connecting to a ParadeDB CNPG Cluster
+
+The command to connect to the primary instance of the cluster will be printed in your terminal. If you do not modify any settings, it will be:
+
+```bash
+kubectl --namespace paradedb-database exec --stdin --tty services/paradedb-rw -- bash
+```
+
+This will launch a shell inside the instance. You can connect via `psql` with:
+
+```bash
+psql -d paradedb
+```
 
 Cluster Configuration
 ---------------------
@@ -238,4 +258,3 @@ refer to  the [CloudNativePG Documentation](https://cloudnative-pg.io/documentat
 | Name | Email | Url |
 | ---- | ------ | --- |
 | ParadeDB | <[email protected]> | <https://paradedb.com> |
-
diff --git a/charts/paradedb/docs/Getting Started.md b/charts/paradedb/docs/Getting Started.md
@@ -1,6 +1,6 @@
 # Getting Started
 
-The CNPG cluster chart follows a convention over configuration approach. This means that the chart will create a reasonable 
+The CNPG cluster chart follows a convention over configuration approach. This means that the chart will create a reasonable
 CNPG setup with sensible defaults. However, you can override these defaults to create a more customized setup. Note that
 you still need to configure backups and monitoring separately. The chart will not install a Prometheus stack for you.
 
@@ -30,7 +30,7 @@ via a GitOps solution or directly via Helm is up to you. The following sections
 
 Currently the chart supports two database types. These are configured via the `type` parameter. These are:
 * `postgresql` - A standard PostgreSQL database.
-* `paradedb` - Postgres for Search and Analytics
+* `paradedb` - Postgres for Search and Analytics.
 
 Depending on the type the chart will use a different Docker image and fill in some initial setup, like extension installation.