docs: update some architecture

docs/architecture/bare-metal-provisioning.md

@@ -0,0 +1,31 @@
+# Bare metal provisioning (PXE boot)
+
+```mermaid
+flowchart TD
+  subgraph controller[Initial controller]
+    Ansible
+    dhcp[DHCP server]
+    tftp[TFTP server]
+    http[HTTP server]
+  end
+
+  machine[Bare metal machine]
+
+  Ansible -. 1 .-> machine
+  machine <-. 2, 3 .-> dhcp
+  machine <-. 4, 5 .-> tftp
+  machine <-. 6, 7 .-> http
+```
+
+1. Ansible: Hey MAC address `xx:xx:xx:xx:xx:xx`, wake up!
+2. Machine: Hello everyone, I just woke up in network mode, could someone please show me how to boot?
+3. DHCP server: I hear you, here's your IP address, proceed to the next server to obtain your bootloader.
+4. Machine: Hello, could you please send me my bootloader?
+5. TFTP server: Here you go. Grab your boot configuration, kernel, and initial ramdisk as well.
+6. Machine: Hi, I just booted into my bootloader, and my boot parameters instructed me to get the installation instructions, packages, etc. from this site.
+7. HTTP server: It's all yours.
+8. Machine: Great, now I can install the OS and reboot!
+
+Here's how it looks like in action:
+
+<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/y-d7btNNAT8" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

docs/architecture/networking.md

@@ -0,0 +1,23 @@
+# Networking
+
+```mermaid
+flowchart TD
+  subgraph LAN
+    laptop/desktop/phone <--> LoadBalancer
+    subgraph k8s[Kubernetes cluster]
+      Pod --> Service
+      Service --> Ingress
+
+      LoadBalancer
+
+      cloudflared
+      cloudflared <--> Ingress
+    end
+    LoadBalancer <--> Ingress
+  end
+
+  cloudflared -- outbound --> Cloudflare
+  Internet -- inbound --> Cloudflare
+```
+
+TODO

docs/architecture/overview.md

@@ -1,4 +1,4 @@
-# Architecture
+# Overview
 
 ## Components
 

docs/architecture/secrets-management.md

@@ -0,0 +1,29 @@
+# Secrets management
+
+- Secrets are stored in [HashiCorp Vault](https://www.vaultproject.io)
+- Vault is managed with [Vault Operator (Bank Vaults)](https://banzaicloud.com/docs/bank-vaults/operator), automatically initialize and unseal
+- Secrets that can be generated are automatically generated and stored in Vault.
+- Integrate with GitOps using [External Secrets Operator](https://external-secrets.io)
+
+!!! info
+
+    Despite the name _External_ Secrets Operator, our Vault is deployed on the same cluster.
+    HashiCorp Vault can be replaced with AWS Secret Manager, Google Cloud Secret Manager, Azure Key Vault, etc.
+
+```mermaid
+flowchart TD
+  subgraph vault-namespace[vault namespace]
+    bank-vaults[Bank Vaults side car] -. init and unseal .- vault[(HashiCorp Vault)]
+    random-secret[Random secrets CronJob] -. generate secrets if not exist .-> vault[(HashiCorp Vault)]
+  end
+
+  subgraph app-namespace[application namespace]
+    ExternalSecret -. generate .-> Secret
+    App -- read --> Secret
+  end
+
+  ClusterSecretStore --> vault
+  ClusterSecretStore --> ExternalSecret
+```
+
+TODO: more details on how to use secrets

docs/installation/production/deployment.md

@@ -12,10 +12,11 @@ Build the lab:
 make
 ```
 
-!!! note
-
-     It will take a while to download Rocky Linux ISO on the first time
-
 Yes it's that simple!
 
-You can read the [architecture document](../../reference/architecture.md) while waiting for the deployment to complete.
+!!! example
+
+    <script id="asciicast-xkBRkwC6e9RAzVuMDXH3nGHp7" src="https://asciinema.org/a/xkBRkwC6e9RAzVuMDXH3nGHp7.js" async></script>
+
+It will take a while to download everything,
+you can read the [architecture document](../../architecture/overview.md) while waiting for the deployment to complete.

docs/installation/production/post-installation.md

@@ -12,6 +12,20 @@ Save the following files to a safe location (like a password manager):
 
 <!-- TODO - `./metal/root-password.txt` -->
 
+## Admin credentials
+
+- ArgoCD:
+    - Username: `admin`
+    - Password: run `./scripts/argocd-admin-password`
+- Vault:
+    - Root token: run `./scripts/vault-root-token`
+- Grafana:
+    - Username: `admin`
+    - Password: `prom-operator` (TODO: use random password)
+- Gitea:
+    - Username: `gitea_admin`
+    - Password: get from Vault
+
 ## Next steps
 
 - [User onboarding](../../user-guide/onboarding.md)

docs/reference/contributing.md

@@ -10,20 +10,6 @@ TODO
 
 TODO
 
-### Documentation
-
-Documents can be viewed at <https://homelab.khuedoan.com>.
-It's running on my other cluster in the [khuedoan/horus](https://github.com/khuedoan/horus) project
-(so if the homelab goes down I can still read the documentation).
-
-To edit and view locally, run:
-
-```
-make docs
-```
-
-Then visit [localhost:8000](http://localhost:8000)
-
 ## Contributors
 
 Here is a list of the contributors who have helped improving my homelab. Big shout-out to them!

docs/runbooks/argocd.md

@@ -1 +1,3 @@
 # ArgoCD
+
+TODO

docs/runbooks/cert-manager.md

@@ -1 +1,3 @@
 # cert-manager
+
+TODO

docs/runbooks/documentation.md

@@ -0,0 +1,33 @@
+# Documentation (this website)
+
+Documents can be viewed at <https://homelab.khuedoan.com>.
+
+## Local development
+
+To edit and view locally, run:
+
+```
+make docs
+```
+
+Then visit [localhost:8000](http://localhost:8000)
+
+## Deployment
+
+It's running on my other cluster in the [khuedoan/horus](https://github.com/khuedoan/horus) project
+(so if the homelab goes down everyone can still read the documentation).
+
+<!-- TODO -->
+<!-- This website is running in both my homelab cluster and on my other cluster in the [khuedoan/horus](https://github.com/khuedoan/horus) project (both in `apps/homelab-docs`), -->
+<!-- with manual DNS switch over in case I want to rebuild either of them (this is the most cost effective way to do this that I can think of). -->
+
+<!-- You don't have to do this, you can host it on 1 cluster just fine. -->
+<!-- But for 0.000000000001% of you who have 2 clusters like me, here's how to switch between them: -->
+
+<!-- - Add the following annotation to the Ingress on the new cluster: `TODO` -->
+<!-- - Go to DNS config on Cloudflare dashboard -->
+<!-- - Find the TXT record for `homelab.khuedoan.com` and switch the `ownerID` between `homelab` and `horus` -->
+<!-- - Wait for the matching CNAME or A record to change -->
+<!-- - Check if you can still access the website -->
+<!-- - Do what ever you want to do -->
+<!-- - (Optional) Switch back to the previous cluster -->

docs/runbooks/gitea.md

@@ -1 +1,3 @@
 # Gitea
+
+TODO

docs/runbooks/longhorn.md

@@ -1 +1,3 @@
 # Longhorn
+
+TODO

docs/runbooks/vault.md

@@ -1,31 +1,3 @@
 # Vault
 
-## Overview
-
-- Secrets are stored in [HashiCorp Vault](https://www.vaultproject.io)
-- Vault is managed with [Vault Operator (Bank Vaults)](https://banzaicloud.com/docs/bank-vaults/operator), automatically initialize and unseal
-- Secrets that can be generated are automatically generated and stored in Vault.
-- Integrate with GitOps using [External Secrets Operator](https://external-secrets.io)
-
-!!! info
-
-    Despite the name _External_ Secrets Operator, our Vault is deployed on the same cluster.
-    HashiCorp Vault can be replaced with AWS Secret Manager, Google Cloud Secret Manager, Azure Key Vault, etc.
-
-```mermaid
-flowchart TD
-  subgraph vault-namespace[vault namespace]
-    bank-vaults[Bank Vaults side car] -. init and unseal .- vault[(HashiCorp Vault)]
-    random-secret[Random secrets CronJob] -. generate secrets if not exist .-> vault[(HashiCorp Vault)]
-  end
-
-  subgraph app-namespace[application namespace]
-    ExternalSecret -. generate .-> Secret
-    App -- read --> Secret
-  end
-
-  ClusterSecretStore --> vault
-  ClusterSecretStore --> ExternalSecret
-```
-
-TODO: more details on how to use secrets
+TODO

mkdocs.yml

@@ -42,6 +42,11 @@ nav:
       - installation/production/configuration.md
       - installation/production/deployment.md
       - installation/production/post-installation.md
+  - Architecture:
+    - architecture/overview.md
+    - architecture/bare-metal-provisioning.md
+    - architecture/secrets-management.md
+    - architecture/networking.md
   - Tutorials:
     - tutorials/manual-dns-setup.md
     - tutorials/create-a-new-user-account.md
@@ -53,6 +58,7 @@ nav:
   - Runbooks:
     - runbooks/argocd.md
     - runbooks/cert-manager.md
+    - runbooks/documentation.md
     - runbooks/gitea.md
     - runbooks/longhorn.md
     - runbooks/vault.md
@@ -60,7 +66,6 @@ nav:
   - User guide:
     - user-guide/onboarding.md
   - Reference:
-    - reference/architecture.md
     - reference/license.md
     - reference/changelog.md
     - reference/roadmap.md