Install: Implement suggestions by CodeRabbit

Author: amotl

docs/feature/cloud/index.md

@@ -65,7 +65,6 @@ needs.
 
 :::{rubric} CrateDB Cloud
 :::
-- {ref}`cloud:index`
 - {ref}`Documentation <cloud:index>`
 - [Web Console]
 

docs/install/cloud/aws/aws-terraform-setup.md

@@ -2,7 +2,7 @@
 
 # Deploy using Terraform
 
-In {ref}`ec2_setup`, we elaborated on how to leverage EC2's functionality to set
+In {ref}`ec2-setup`, we elaborated on how to leverage EC2's functionality to set
 up a CrateDB cluster. Here, we will explore how to automate this kind of setup.
 
 [Terraform] is an infrastructure as code tool, often used as an abstraction

docs/install/cloud/aws/s3-setup.md

@@ -25,8 +25,8 @@ instances.
 
 ### Authentication
 
-It is recommended to restrict the permissions of CrateDB on the S3 to only the
-required extend. First, an IAM role is required. This [AWS guide] gives a
+It is recommended to restrict the permissions of CrateDB on S3 to only the
+required extent. First, an IAM role is required. This [AWS guide] gives a
 short description of how to create a policy offer using the CLI or the AWS
 management console. Further, access of the snapshot to the S3 bucket needs to
 be restricted. An example policy file granting anybody access to a bucket

docs/install/cloud/azure/terraform.md

@@ -2,7 +2,7 @@
 
 # Deploy using Terraform
 
-In {ref}`azure_vm_setup`, we elaborated on how to leverage Azure's functionality to
+In {ref}`azure-vm-setup`, we elaborated on how to leverage Azure's functionality to
 set up a CrateDB cluster. Here, we will explore how to automate this kind of
 setup.
 

docs/install/cloud/azure/vm.md

@@ -23,7 +23,7 @@ under the *new* left hand panel of the Azure portal.
 ### Create a network security group
 
 CrateDB uses two ports, one for inter-node communication (`4300`) and one for
-it's http endpoint (`4200`), so access to these needs to be opened.
+its HTTP endpoint (`4200`), so access to these needs to be opened.
 
 Create a *New Security Group*, giving it a name and assigning it to the
 'Resource Group' just created.
@@ -32,7 +32,7 @@ Create a *New Security Group*, giving it a name and assigning it to the
 :alt: Create New Security Group
 ```
 
-Find that security group in your resources list and open it's settings,
+Find that security group in your resources list and open its settings,
 navigating to the *Inbound security rules* section.
 
 ```{image} /_assets/img/install/cloud/azure-nsg-inbound.png
@@ -71,7 +71,7 @@ earlier to the subnet.
 ### Create virtual machines
 
 Next create virtual machines to act as your CrateDB nodes. In this tutorial, I
-chose two low-specification Ubuntu 14.04 servers, but you likely have your own
+chose two low-specification Ubuntu servers, but you likely have your own
 preferred configurations.
 
 Most importantly, make sure you select the Virtual Network created earlier.
@@ -142,14 +142,14 @@ the same steps as for Azure and Linux.
 ### Create virtual machines
 
 Similar steps to creating Virtual Machines for Azure and Linux, but create the
-VM based on the 'Windows Server 2012 R2 Datacenter' image.
+VM based on a recent "Windows Server LTS" image.
 
 ### Install CrateDB
 
 *Note that these instructions should be followed on each VM in your cluster.*
 
 To install CrateDB on Windows Server, you will need a [Java JDK installed].
-Ensure that the `JAVA*HOME` environment variable is set.
+Ensure that the `JAVA_HOME` environment variable is set.
 
 ```{image} /_assets/img/install/cloud/azure-envvar.png
 :alt: Environment Variables
@@ -171,7 +171,7 @@ We need to allow the ports CrateDB uses through the Windows Firewall
 :alt: Firewall configuration
 ```
 
-Start crate by running `bin/crate`.
+Start CrateDB by running `.\bin\crate.bat` (PowerShell) or `bin\crate.bat` (CMD).
 
 [3.3]: https://github.com/crate/crate/blob/3.3/blackbox/docs/config/cluster.rst#discovery
 [java jdk installed]: https://www.oracle.com/java/technologies/downloads/#java8

docs/install/container/docker.md

@@ -22,6 +22,8 @@ The official [CrateDB Docker image].
 
 ## Quick start
 
+(container-create-cluster)=
+
 ### Creating a cluster
 
 To get started with CrateDB and Docker, you will create a three-node cluster
@@ -55,7 +57,7 @@ container `crate03` will run cluster node `crate03`.
 
 You can then create your first CrateDB container and node, like this:
 
-```
+```shell
 sh$ docker run --rm -d \
       --name=crate01 \
       --net=crate \
@@ -250,7 +252,8 @@ The CrateDB Shell, `crash`, is bundled with the Docker image.
 
 If you wanted to run `crash` inside a user-defined network called `crate`
 and connect to three hosts named `crate01`, `crate02`, and `crate03`
-(i.e. the example covered in the [Creating a Cluster] section) you could run:
+(i.e. the example covered in the {ref}`container-create-cluster` section)
+you could run:
 
 ```shell
 $ docker run --rm -ti \
@@ -470,7 +473,7 @@ example:
 ```shell
 $ docker run -d \
     --cpus 1.5 \
-    --memory 1g \
+    --memory 2g \
     --env CRATE_HEAP_SIZE=1g \
     crate \
     crate -Cnetwork.host=_site_

docs/install/container/kubernetes/kubernetes.md

@@ -6,7 +6,7 @@
 CrateDB and Kubernetes are a great match.
 :::
 
-CrateDB’s [horizontally scalable] `shared-nothing architecture` lends itself
+CrateDB’s [horizontally scalable] [shared-nothing architecture] lends itself
 well to [containerization].
 
 [Kubernetes] is an open-source container orchestration system for the
@@ -15,8 +15,8 @@ management, deployment, and scaling of containerized systems.
 Together, Docker and Kubernetes are a fantastic way to deploy and scale CrateDB.
 
 :::{NOTE}
-While Kubernetes works with a variety of container technologies, this
-document only covers its use with Docker.
+While Kubernetes supports multiple container runtimes, this document
+uses Docker-compatible container images.
 :::
 
 :::{SEEALSO}
@@ -41,7 +41,7 @@ You can create a resource like so:
 
 ```console
 sh$ kubectl create -f crate-controller.yaml --namespace crate
-statefulset.apps/crate-controller created
+statefulset.apps/crate created
 ```
 
 Here, we are creating a [StatefulSet] controller in the `crate` namespace
@@ -149,6 +149,12 @@ load balancers.
 For local development, [Minikube] provides a LoadBalancer service.
 :::
 
+:::{WARNING}
+Ensure proper network controls and authentication are in place before
+exposing ports 4200 (HTTP) and 5432 (PostgreSQL) via a LoadBalancer.
+Restrict source IPs and configure users/roles to avoid unauthorized access.
+:::
+
 ### Controller
 
 A Kubernetes [pod] is a group of one or more containers. Pods are designed to
@@ -213,7 +219,7 @@ spec:
         # Use the CrateDB 5.1.1 Docker image.
         image: crate:5.1.1
         # Pass in configuration to CrateDB via command-line options.
-        # We are setting the name of the node's explicitly, which is
+        # We are setting the node name explicitly, which is
         # needed to determine the initial master nodes. These are set to
         # the name of the pod.
         # We are using the SRV records provided by Kubernetes to discover
@@ -228,7 +234,7 @@ spec:
           - -Cgateway.expected_data_nodes=${EXPECTED_NODES}
           - -Cpath.data=/data
         volumeMounts:
-              # Mount the `/data` directory as a volume named `data`.
+            # Mount the `/data` directory as a volume named `data`.
             - mountPath: /data
               name: data
         resources:
@@ -247,7 +253,7 @@ spec:
           name: postgres
         # Environment variables passed through to the container.
         env:
-          # This is variable is detected by CrateDB.
+          # This variable is detected by CrateDB.
         - name: CRATE_HEAP_SIZE
           value: "256m"
           # The rest of these variables are used in the command-line
@@ -333,34 +339,31 @@ You can then use this in your controller configuration with something like this:
 [...]
   volumeClaimTemplates:
     - metadata:
-        name: persistant-data
+        name: cratedb-data
       spec:
         # This will create one 100GB read-write Azure Managed Disks volume
         # for every CrateDB pod.
         accessModes: [ "ReadWriteOnce" ]
         storageClassName: crate-premium
         resources:
           requests:
-            storage: 100g
+            storage: 100Gi
 ```
 
 [azure managed disks]: https://azure.microsoft.com/en-us/pricing/details/managed-disks/
 [configuration]: https://kubernetes.io/docs/concepts/configuration/overview/
 [containerization]: https://www.docker.com/resources/what-container
 [cratedb docker image]: https://hub.docker.com/_/crate/
-[docker]: https://www.docker.com/
 [horizontally scalable]: https://en.wikipedia.org/wiki/Scalability#Horizontal_(scale_out)_and_vertical_scaling_(scale_up)
 [ingress]: https://kubernetes.io/docs/concepts/services-networking/ingress/
 [kubernetes]: https://kubernetes.io/
 [loadbalancer]: https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer
 [managed]: https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/
 [minikube]: https://kubernetes.io/docs/setup/minikube/
-[persistent volume]: https://kubernetes.io/docs/concepts/storage/persistent-volumes/
 [persistent volumes]: https://kubernetes.io/docs/concepts/storage/persistent-volumes/
 [pod]: https://kubernetes.io/docs/concepts/workloads/pods/
 [rolling update strategy]: https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#rolling-updates
 [service]: https://kubernetes.io/docs/concepts/services-networking/service/
-[services]: https://kubernetes.io/docs/concepts/services-networking/service/
 [setting up your first cratedb cluster on kubernetes]: https://cratedb.com/blog/run-your-first-cratedb-cluster-on-kubernetes-part-one
 [shared-nothing architecture]: https://en.wikipedia.org/wiki/Shared-nothing_architecture
 [statefulset]: https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/

docs/install/debian-ubuntu.md

@@ -4,13 +4,13 @@
 (install-debian)=
 (install-ubuntu)=
 
-# CrateDB on Debian, Ubuntu, and Derivates
+# CrateDB on Debian, Ubuntu, and Derivatives
 
 :::{div} sd-text-muted
 Install CrateDB [deb] packages using the [apt] package manager.
 :::
 
-This installation method is suitable for Debian systems and derivates
+This installation method is suitable for Debian systems and derivatives
 like Ubuntu.
 
 ## Package repository
@@ -63,7 +63,7 @@ sh$ sudo systemctl start crate
 
 Once the service is up and running, you can access CrateDB by visiting:
 
-```
+```text
 http://localhost:4200/
 ```
 

docs/install/redhat.md

@@ -3,22 +3,22 @@
 (install-redhat)=
 (install-suse)=
 
-# CrateDB on Red Hat, SUSE, and Derivates
+# CrateDB on Red Hat, SUSE, and Derivatives
 
 :::{div} sd-text-muted
 Install CrateDB [RPM] packages using the [DNF], [YUM], or [ZYpp] package managers.
 :::
 
-This installation method is suitable for RedHat Enterprise Linux (RHEL) and compatible
-systems like Fedora, CentOS, Rocky Linux, AlmaLinux, AWS Linux, Oracle Linux, or
+This installation method is suitable for Red Hat Enterprise Linux (RHEL) and compatible
+systems like Fedora, CentOS, Rocky Linux, AlmaLinux, Amazon Linux, Oracle Linux, or
 Scientific Linux. Installation also works on openSUSE and SUSE Linux Enterprise Server
 (SLES) systems.
 
 ## Package repository
 
 To register with the CrateDB package repository, create a file called `cratedb.repo`
-in the `/etc/yum.repos.d/` directory for RedHat based distributions, or in the
-`/etc/zypp/repos.d/` directory for OpenSuSE based distributions, containing:
+in the `/etc/yum.repos.d/` directory for Red Hat based distributions, or in the
+`/etc/zypp/repos.d/` directory for openSUSE-based distributions, containing:
 
 ```ini
 [cratedb-ce-stable]
@@ -50,6 +50,19 @@ the repository as indicated in the sample installation command below.
 CrateDB provides both *stable release* and *testing release* channels. You
 can read more about the [release workflow].
 
+## Prerequisites
+
+If `sudo` is missing, run this as root:
+```shell
+# Red Hat-compatible systems
+dnf install sudo
+```
+or:
+```shell
+# SUSE-based systems
+zypper install sudo
+```
+
 ## Install CrateDB
 
 With everything set up, you can install CrateDB:
@@ -60,7 +73,7 @@ sudo dnf install --enablerepo=cratedb-ce-stable crate
 
 :::{TIP}
 On older Red Hat and CentOS installations, please use the `yum` command
-instead of `dnf`. On SUSE based installations, please use the `zypper`
+instead of `dnf`. On SUSE-based installations, please use the `zypper`
 command.
 :::
 
@@ -76,9 +89,6 @@ to do it on the first installation of CrateDB, you can also import it
 into your repository keyring, like that:
 
 ```shell
-# Install prerequisites.
-yum install sudo
-
 # Import the public GPG key for verifying the package signatures.
 sudo rpm --import https://cdn.crate.io/downloads/yum/RPM-GPG-KEY-crate
 ```

docs/install/windows.md

@@ -16,6 +16,11 @@ us][contact us] so we can work with you on a solution.
    command-line shell or by using a GUI tool like [7-Zip]. We recommend
    using [PowerShell] when using terminal:
 
+   ```powershell
+   # Extract Zip archive
+   Expand-Archive -Path .\crate-*.zip -DestinationPath .
+   ```
+
    ```doscon
    # Extract Zip archive
    unzip -o crate-*.zip