From bc562a697483d22c212faf1f1a2be50e151d923f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20No=C3=ABl?= <21990816+philippemnoel@users.noreply.github.com> Date: Wed, 2 Oct 2024 18:46:33 -0400 Subject: [PATCH] docs: Clarify the docs (#42) --- README.md | 30 +++++++++++++++++----- charts/paradedb/README.md | 33 +++++++++++++++++++------ charts/paradedb/docs/Getting Started.md | 4 +-- 3 files changed, 52 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index b885da8f3..984d23e3c 100644 --- 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 index 1338bddef..2d5c9fef4 100644 --- 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 | | | - diff --git a/charts/paradedb/docs/Getting Started.md b/charts/paradedb/docs/Getting Started.md index 025f661db..67feb8891 100644 --- 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.