feat: add byo-git documentation

docs/for-ops/disaster-recovery/overview.md

@@ -29,6 +29,22 @@ This guide has the following prerequisites and limitations that should be checke
 
 7. All instructions assume you are familiar with essential Kubernetes tools such as `kubectl` and have access to the Kubernetes API. Usage of TUI applications such as `k9s` from the administration terminal is strongly recommended.
 
+## BYO Git
+
+When using an external Git repository (BYO Git), disaster recovery is significantly simplified. The platform configuration is already stored externally, so Gitea backup and restore is not required. To restore the platform, you only need:
+
+- The age keys (`privateKey` and `publicKey`) used for SOPS encryption.
+- Access credentials to the external Git repository.
+
+Make sure to store the age `privateKey` securely outside the cluster.
+The `privateKey` can be retrieved from the cluster with the following command:
+
+```bash
+kubectl get secret apl-sops-secrets -n apl-operator -o jsonpath='{.data.SOPS_AGE_KEY}' | base64 --decode
+```
+
+See the [BYO Git installation guide](../../get-started/installation/byo-git.md) for more details.
+
 ## Guides
 
 - [Gitea](gitea.md): Restoring the platform's Gitea database and repositories from the application backup

docs/get-started/installation/byo-git.md

@@ -0,0 +1,108 @@
+---
+slug: byo-git
+title: BYO Git
+sidebar_label: BYO Git
+---
+
+By default, the App Platform installs Gitea as the built-in Git repository to store platform configuration (the `values` repository). If you prefer to use your own external Git repository, you can disable Gitea and configure the platform to use an external Git provider such as GitHub or GitLab.
+
+## Prerequisites
+
+- An empty git repository accessible from kubernetes cluster via the HTTPS protocol.
+- A personal access token with read/write access to the repository.
+- The repository should be empty or initialized with a default branch.
+
+## Advantages of BYO Git
+
+- Use your existing Git workflows and access controls.
+- Simplified disaster recovery: the platform configuration is stored externally, so you only need to back up your age keys to restore the platform.
+- No need to manage and back up the built-in Gitea instance.
+
+## Configure the values
+
+To install with BYO Git, disable Gitea and add the Git configuration to your `values.yaml`:
+
+```yaml
+apps:
+  gitea:
+    enabled: false
+  cert-manager:
+    issuer: letsencrypt
+    email: admin@example.com
+cluster:
+  domainSuffix: example.com
+  name: my-cluster
+  provider: linode
+dns:
+  domainFilters:
+    - example.com
+  provider:
+    linode:
+      apiToken: '<your-linode-api-token>'
+kms:
+  sops:
+    provider: age
+otomi:
+  hasExternalDNS: true
+  git:
+    repoUrl: https://github.com/<owner>/<repo>
+    username: <git-username>
+    password: <personal-access-token>
+    email: <git-email>
+    branch: main
+```
+
+### Git configuration options
+
+| Parameter            | Description                                    |
+| -------------------- | ---------------------------------------------- |
+| `otomi.git.repoUrl`  | The HTTPS URL of the external Git repository   |
+| `otomi.git.username` | The Git username for authentication            |
+| `otomi.git.password` | A personal access token with read/write access |
+| `otomi.git.email`    | The email address used for Git commits         |
+| `otomi.git.branch`   | The branch to use (e.g. `main`)                |
+
+## Disaster recovery with BYO Git
+
+Since the configuration parameters (the values repository) is stored outside the cluster the disaster recover process is straightforward. In the recovery mode the `values.yaml` file must contian the following parameters:
+
+- `kms.sops.age` with `privateKey` and `publicKey`
+- `otomi.git` configuration options
+- `installation.mode` set to `recovery`
+
+For example:
+
+```yaml
+cluster:
+  name: your-cluster-name
+  provider: linode
+otomi:
+  git:
+    repoUrl: https://github.com/<owner>/<repo>
+    username: <git-username>
+    password: <personal-access-token>
+    email: <git-email>
+    branch: main
+kms:
+  sops:
+    age:
+      privateKey: '<your-age-private-key>'
+      publicKey: '<your-age-public-key>'
+    provider: age
+installation:
+  mode: recovery
+```
+
+The following command can be used to re-install the App Platform:
+
+```bash
+helm install -f values.yaml apl apl/apl
+```
+
+> Make sure to store your age keys securely outside of the cluster (e.g. in a password manager or secrets vault). Without them you won't be able to decrypt the secrets stored in the git repository.
+
+> This procedure works out of the box for App Platform instancies that manage their own DNS records (via external-dns and cert manager).
+
+> This procedure does not cover the recovery of databases used by Gitea and/or Harbor.
+
+See the [disaster recovery documentation](../../for-ops/disaster-recovery/overview.md) for the full procedure.

docs/get-started/installation/helm.md

@@ -57,7 +57,7 @@ The `apl` Helm chart deploys the operator to the `apl-operator` namespace.
 The installation is completed once the App Platform URL is reachable. The URL will be stored in the `welcome` config map:
 
 ```bash
-kubectl get configmap welcome -n apl-operator -oyaml
+kubectl get configmap welcome -n apl-operator -o yaml
 ```
 
 You can follow the operator logs by executing the below command:

docs/get-started/installation/linode.md

@@ -145,7 +145,7 @@ The `apl` Helm chart deploys the operator to the `apl-operator` namespace.
 The installation is completed once the App Platform URL is reachable. The URL will be stored in the `welcome` config map:
 
 ```bash
-kubectl get configmap welcome -n apl-operator -oyaml
+kubectl get configmap welcome -n apl-operator -o yaml
 ```
 
 You can follow the operator logs by executing the below command:

docs/get-started/installation/overview.md

@@ -56,4 +56,8 @@ Install with an entrypoint for an external gateway.
 
 Install using a BYO (wild card) certificate.
 
+### [Bring Your Own Git](byo-git.md)
+
+Install using an external Git repository (e.g. GitHub or GitLab) instead of the built-in Gitea.
+
 ---

sidebar-docs.js

@@ -15,6 +15,7 @@ module.exports = {
           "get-started/installation/sops",
           "get-started/installation/entrypoint",
           "get-started/installation/byo-wildcard",
+          "get-started/installation/byo-git",
         ],
       },
       "get-started/installation/post-install-steps",