[Feat] Update Install Guide for v4.0.0

content/versions/v4.0.0/_index.md

@@ -0,0 +1,30 @@
+---
+title: v4.0.0
+description: User guides, deploy docs, references, and deep dives about the
+  Rhize manufacturing data hub.
+cascade:
+  type: versions
+  v: "4.0.0"
+---
+
+<!-- define h1 for all other pages in Title in frontmatter -->
+
+<h1 class="post-title">
+The Rhize Manufacturing Data Hub
+</h1>
+
+Rhize is a real-time, event-driven manufacturing data hub.
+
+Rhize unites all events from your manufacturing processes, relates these events as a single graph structure, 
+and provides access to any combination of them through a single API endpoint.
+The tight integration of all levels of manufacturing data, from real-time sensor data to operations orders, serves a wide variety of business needs, including as:
+
+- **A manufacturing knowledge graph.** Help humans and algorithms analyze plant processes and discover places to optimize.
+- **An integrator of systems.** Orchestrate processes across applications to standardize, coordinate, and transform data flows.
+- **A backend for {{< abbr "MES" >}} applications.** Rapidly build frontends on top of the database and workflow engine.
+  Design the MES system that makes sense for your processes and people.
+
+
+{{< card-list >}}
+
+

content/versions/v4.0.0/deploy/_index.md

@@ -0,0 +1,38 @@
+---
+title: Deploy
+description: >-
+  A collection of pages to administrate Rhize: install, upgrade, back up, and more.
+weight: 100
+icon: server
+identifier: deploy
+cascade:
+  icon: server
+  domain_name: libremfg.ai
+  brand_name: Libre
+  application_name: libre
+  db: libreBaas
+  pre_reqs: |-
+    - Optional: [kubectx](https://github.com/ahmetb/kubectx) utilities
+        - `kubectx` to manage multiple clusters
+        - `kubens` to switch between and configure namespaces easily
+    - Optional: the [k8 Lens IDE](https://k8slens.dev), if you prefer to use Kubernetes graphically
+  k8s_cluster_ns: |-
+    ```bash
+    ## context
+    kubectl config current-context
+    ## namespace
+    kubectl get namespace
+    ```
+
+    To change the namespace for all subsequent [`kubectl` commands](https://kubernetes.io/docs/reference/kubectl/cheatsheet/) to `libre`, run this command:
+
+    ```bash
+    kubectl config set-context --current --namespace=libre
+    ```
+
+---
+
+A collection of pages to administrate Rhize: install, upgrade, back up, and more.
+
+
+{{< card-list >}}

content/versions/v4.0.0/deploy/backup/_index.md

@@ -0,0 +1,21 @@
+---
+date: "2023-09-12T19:35:35+11:00"
+title: Back up
+description: Guides to back up your data on Rhize
+categories: ["how-to"]
+weight: 200
+cascade:
+  icon: database
+---
+
+Backup is critical to ensure reliability and recovery.
+
+These guides show you how to back up different services and data on Rhize.
+They also serve as blueprints for automation.
+
+Your organization must determine how frequently you backup services, and how long you store them for.
+The correct practice here is highly contextual,
+depending on the size of the data, the importance of the data, and the general regulatory and governance demands of your industry.
+
+
+{{< card-list >}}

content/versions/v4.0.0/deploy/backup/audit.md

@@ -0,0 +1,52 @@
+---
+title: 'Back up Audit PostgreSQL'
+date: '2024-03-26T11:20:56-03:00'
+categories: ["how-to"]
+description: How to backup Audit PostgreSQL on your Rhize deployment
+weight: 300
+---
+
+This guide shows you the procedure to backup your Audit PostgreSQL database on your Rhize Kubernetes deployment.
+
+## Prerequisites
+
+Before you start, ensure you have the following:
+
+- A designated backup location, for example `~/rhize-backups/libre-audit`.
+- Access to the [Rhize Kubernetes Environment](/deploy/install/setup-kubernetes)
+{{% param pre_reqs %}}
+
+
+Also, before you start, confirm you are in the right context and namespace.
+
+{{% param k8s_cluster_ns %}}
+
+## Steps
+
+To back up Audit PostgreSQL, follow these steps:
+
+1. Check the logs for the Audit pods, either in Lens or with [`kubectl logs`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#logs).
+    Ensure there are no errors.
+
+1. Retrieve the Audit user password using the following command:
+
+
+    ```bash
+    kubectl get secret <SECRET-NAME> -o jsonpath="{.data.<SECRET-KEY>}" | base64 --decode
+    ```
+
+1. Execute a command on the Audit Postgres pod to perform a full backup:
+
+    ```bash
+    kubectl exec -i audit-postgres-0 -- pg_dumpall -U <DB_USER> | gzip > audit-postgres-backup-$(date +"%Y%m%dT%I%M%p").sql.gz
+    ```
+
+On success, the backup creates a GZIP file, `audit-postgres-backup-YYYYMMDDTHHMMSS.sql.gz`.
+To check that the backup succeeded, unzip the files and inspect the data.
+
+## Next Steps
+
+- To back up other Rhize services, read how to backup:
+  - [Keycloak]({{< relref "keycloak" >}}).
+  - [Grafana]({{< relref "grafana" >}}).
+  - [The Graph Database]({{< relref "graphdb" >}}).

content/versions/v4.0.0/deploy/backup/binary.md

@@ -0,0 +1,79 @@
+---
+title: 'Back up the Graph DB to S3'
+date: '2024-11-04T11:01:46-03:00'
+categories: ["how-to"]
+description: How to back up the Rhize graph database to Amazon S3 storage.
+weight: 100
+---
+
+This guide shows you how to back up the Rhize Graph database to Amazon S3 and S3-compatible storage.
+
+## Prerequisites
+
+Before you start, ensure you have the following:
+
+
+- A designated S3 backup location, for example `s3://s3.<AWS-REGION>.amazonaws.com/<AWS-BUCKET-NAME>`.
+- Access to your [Rhize Kubernetes Environment]({{< relref "../install" >}})
+{{% param pre_reqs %}}.
+
+
+Before you start, confirm you are in the right context and namespace:
+
+{{% param "k8s_cluster_ns" %}}
+
+## Steps
+
+To back up the database, follow these steps:
+
+1. Check the logs for the alpha and zero pods, either in Lens or with [`kubectl logs`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#logs).
+    Ensure there are no errors.
+
+    ```bash
+    kubectl logs {{< param application_name >}}-baas-baas-alpha-0 --tail=80
+    ```
+1. Set the following environmental variables:
+   - `AWS_ACCESS_KEY_ID`. Your AWS access key with permissions to write to the destination bucket 
+   - `AWS_SECRET_ACCESS_KEY`. Your AWS access key with permissions to write to the destination bucket
+   - `AWS_SESSION_TOKEN`. Your AWS session token (if required)
+
+1. Make a POST request to your Keycloak `/token` endpoint to get an `access_token` value.
+For example, with `curl` and `jq`:
+
+    ```bash
+    ## replace USERNAME and PASSWORD with your credentials
+    [email protected] \
+    && PASSWORD=password \
+    && curl --location \
+      --request POST "${BAAS_OIDC_URL}/realms/libre/protocol/openid-connect/token" \
+      --header 'Content-Type\ application/x-www-form-urlencoded' \
+      --data-urlencode 'grant_type=password' \
+      --data-urlencode "username=<USERNAME>" \
+      --data-urlencode "password=<PASSWORD>"  \
+      --data-urlencode "client_id=<BASS_CLIENT_ID>" \
+      --data-urlencode "client_secret=<BASS_CLIENT_SECRET>" | jq .access_token
+    ```
+
+1. Using the token from the previous step, send a POST to `<alpha service>:8080/admin` to create a backup of the node to your S3 bucket.
+For example, with `curl`:
+
+    ```bash
+   curl --location 'http://alpha:8080/admin' \
+   --header 'Content-Type: application/json' \
+   --header 'Authorization: Bearer <TOKEN>' \
+   --data '{"query":"mutation {\n  backup(input: {destination: \"s3://s3.<AWS-REGION>.amazonaws.com/<AWS-BUCKET-NAME>\"}) {\n    response {\n      message\n      code\n    }\n    taskId\n  }\n}","variables":{}}'
+   ```
+
+1. List available backups to confirm your backup succeeded:
+
+    ```bash
+    curl --location 'http://alpha:8080/admin' \
+   --header 'Content-Type: application/json' \
+   --header 'Authorization: Bearer <TOKEN>' \
+   --data '{"query":"query backup {\n\tlistBackups(input: {location: \"s3://s3.<AWS-REGION>>.amazonaws.com/<AWS-BUCKET-NAME>\"}) {\n\t\tbackupId\n\t\tbackupNum\n\t\tpath\n\t\tsince\n\t\ttype\n\t}\n}","variables":{}}'
+    ```
+
+## Next Steps
+
+- Test the [Restore Graph Database From S3]({{< relref "../restore/binary" >}}) procedure to ensure you can recover data from Amazon S3 in case of an emergency.
+- To back up other Rhize services, read how to backup [Grafana]({{< relref "grafana" >}}).

content/versions/v4.0.0/deploy/backup/grafana.md

@@ -0,0 +1,105 @@
+---
+title: 'Back up Grafana'
+date: '2023-10-18T11:01:56-03:00'
+categories: ["how-to"]
+description: How to backup Grafana on your Rhize deployment
+weight: 300
+---
+
+This guide shows you the procedure to back up Grafana on your Rhize Kubernetes deployment.
+For general instructions, refer to the official [Back up Grafana](https://grafana.com/docs/grafana/latest/administration/back-up-grafana/) documentation.
+
+## Prerequisites
+
+Before you start, ensure you have the following:
+
+- A designated backup location, for example `~/rhize-backups/grafana`.
+- Access to the [Rhize Kubernetes Environment](/deploy/install/setup-kubernetes)
+{{% param pre_reqs %}}
+
+
+Also, before you start, confirm you are in the right context and namespace.
+
+{{% param k8s_cluster_ns %}}
+
+## Steps
+
+To back up the Grafana, follow these steps:
+
+1. Check the logs for the Grafana pods, either in Lens or with [`kubectl logs`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#logs).
+    Ensure there are no errors.
+
+1. Open a pod shell for one of the Grafana pods:
+
+     ```bash
+     kubectl exec --stdin --tty <GRAFANA_POD_NAME> -- /bin/bash
+     ```
+
+    For details, read the Kubernetes topic [Get Shell to a Running Container](https://kubernetes.io/docs/tasks/debug/debug-application/get-shell-running-container/).
+
+1. Use `tar` to backup the Grafana data and `conf` directories:
+
+     ```bash
+     ## Data Directory Backup Command
+     tar -v -c -f /home/grafana/grafana-data-$(date +"%Y-%m-%dT%H.%M.%S").tar.gz /var/lib/grafana
+     ## Conf Directory Backup Command
+     tar -v -c -f /home/grafana/grafana-conf-$(date +"%Y-%m-%dT%H.%M.%S").tar.gz /usr/share/grafana/conf
+     ```
+
+1. Change to the backup directory. For example:
+
+    ```bash
+    cd /home/grafana/
+    ```
+
+1. Check for the latest `.gz` files (for example, with `ls -lt`).
+   There should be new backup `data` and `conf` files whose names include timestamps from when you ran the preceding `tar` commands.
+
+1. Create a checksum file for the latest backups:
+
+   ```bash
+   sha256sum <LATEST_DATA_FILE>.tar.gz <LATEST_CONF_FILE>.tar.gz > backup.sums
+   ```
+
+
+1. Exit the container shell, and then copy files out of the container to your backup location:
+
+    ```bash
+    ## exit shell
+    exit
+    ## copy container files to backup
+    kubectl cp <GRAFANA_POD>:/home/grafana/<NEW_DATA_BACKUP_FILENAME> \
+    ./<NEW_DATA_BACKUP_FILENAME> -c grafana
+
+    kubectl cp <GRAFANA_POD>:/home/grafana/<NEW_CONF_BACKUP_FILENAME> \
+    ./<NEW_CONF_BACKUP_FILENAME> -c grafana
+    kubectl cp <GRAFANA_POD>:/home/grafana/backup.sums \
+    ./backup.sums -c grafana
+    ```
+
+## Confirm success
+
+
+To confirm the backup, check their sha256 sums and their content.
+
+To check the sums:
+
+1. Change to the directory where you sent the backups:
+
+     ```bash
+     cd <BACKUP>/<ON_YOUR_DEVICE>/
+     ```
+
+1. Confirm the checksums match:
+
+     ```bash
+     sha256sum -c backup.sums \
+     <LATEST_DATA_FILE>.tar.gz <LATEST_CONF_FILE>.tar.gz
+     ```
+
+To check that the content is correct, unzip the files and inspect the data.
+
+## Next steps
+
+- Test the [Restore Grafana]({{< relref "../restore" >}}) procedure to ensure you can recover data in case of an emergency.
+- To back up other Rhize services, read how to backup [the Graph Database]({{< relref "graphdb" >}}).