From b58b2f6652e963d48e616c942c381bf7a498decc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc=20Sch=C3=A4fer?= <git@marcschaeferger.de>
Date: Mon, 15 Sep 2025 19:26:16 +0200
Subject: [PATCH] feat(self-host): add official Newt Kubernetes Helm install

---
 self-host/manual/kubernetes.mdx | 115 ++++++++++++++++++++++++++++++++
 1 file changed, 115 insertions(+)
 create mode 100644 self-host/manual/kubernetes.mdx

diff --git a/self-host/manual/kubernetes.mdx b/self-host/manual/kubernetes.mdx
new file mode 100644
index 0000000..3f5b1ee
--- /dev/null
+++ b/self-host/manual/kubernetes.mdx
@@ -0,0 +1,115 @@
+---
+title: "Kubernetes Installation"
+description: "How to deploy Newt on Kubernetes"
+---
+
+This guide walks you through setting up Newt on Kubernetes using Helm.
+
+This guide assumes you already are familiar with Kubernetes concepts and you fulfill the following Global prerequisites:
+
+## Global Prerequisites
+
+<Check>
+- Kubernetes Cluster (v1.28.15+)
+- Access to the Kubernetes Cluster
+- Helm (v3.0+) installed, see <Link href="https://helm.sh/docs/intro/install/">Helm install docs</Link>
+</Check>
+
+<Tip>
+**Recommended**: Helm Chart Installation.
+</Tip>
+
+---
+
+<Tabs>
+	<Tab title="Helm">
+
+		# Helm Installation
+
+		<Tip>
+		All Fossorial Helm charts are available on Artifact Hub. See <Link href="https://artifacthub.io/packages/search?org=fosrl">Fossorial Charts</Link>.
+		</Tip>
+
+		## Install Newt
+
+		<Steps>
+		  <Step title="Add Fossorial Helm repo">
+		    ```bash
+		    helm repo add fossorial https://charts.fossorial.io
+		    helm repo update fossorial
+		    helm search repo fossorial
+		    ```
+		  </Step>
+		  <Step title="Prepare Installation files">
+
+			Prepare your Newt credentials:
+		    ```env title="newt-cred.env"
+			PANGOLIN_ENDPOINT=<your-endpoint>
+			NEWT_ID=<your-id>
+			NEWT_SECRET=<your-secret>
+			```
+
+		    Prepare a values file with your desired configuration.
+
+			<Tip>See <Link href="https://github.com/fosrl/helm-charts/tree/main/charts/newt">Newt chart values configuration options</Link>.</Tip>
+
+		    ```yaml title="values-newt.yaml"
+			newtInstances:
+			  - name: main
+			    enabled: true
+			    auth:
+			      existingSecretName: newt-cred
+			      keys:
+			        endpointKey: PANGOLIN_ENDPOINT
+			        idKey: NEWT_ID
+			        secretKey: NEWT_SECRET
+		    ```
+			</Step>
+			<Step title="Newt Installation">
+
+			Create a Kubernetes Secret from the env file created earlier:
+			```bash
+			kubectl create secret generic newt-cred -n newt --from-env-file=newt-cred.env
+			```
+
+			Install Newt with Helm:
+		    ```bash
+		    helm install my-newt fossorial/newt \
+		      -n newt --create-namespace \
+		      -f values-newt.yaml
+		    ```
+
+			Change the release name (`my-newt`), namespace (`newt`), and values filename as needed.
+		  </Step>
+		  <Step title="Upgrade or rollback">
+		    ```bash
+			# Update repo to get latest charts
+			helm repo update fossorial
+			# Upgrade Newt (after editing values)
+		    helm upgrade my-newt fossorial/newt -n newt -f values-newt.yaml
+		    ```
+			```bash
+			# Roll back to a previous revision
+		    helm rollback my-newt 1 -n newt
+		    ```
+		  </Step>
+		</Steps>
+	</Tab>
+</Tabs>
+
+---
+
+## Customizing Your Values
+
+All configuration options are documented in the respective repositories:
+
+- <Link href="https://github.com/fosrl/helm-charts/tree/main/charts/newt">Newt Helm chart values</Link>
+
+---
+
+## References
+
+ - <Link href="https://github.com/fosrl/helm-charts">All Fossorial Helm Charts repo</Link>
+ - <Link href="https://github.com/fosrl/kubernetes">All Fossorial Kubernetes resources</Link>
+ - <Link href="https://github.com/fosrl/pangolin-kube-controller">Pangolin Kubernetes Controller</Link>
+ - <Link href="https://helm.sh/docs/">Helm documentation</Link>