refactor(docs): apply the Diátaxis framework

Squashed commit of the following:

commit 257867f196376df55fa0f57edbdf33967b1da04e
Author: Khue Doan <mail@khuedoan.com>
Date:   Sun Sep 18 16:45:42 2022 +0700

    refactor(docs): apply the Diátaxis framework

.yamllint.yaml

@@ -1,5 +1,6 @@
 ignore: |
   templates/
+  mkdocs.yml
 
 extends: default
 

README.md

@@ -249,6 +249,7 @@ References:
 - [Initialize GitOps repository on Gitea and integrate with Tekton by RedHat](https://github.com/redhat-scholars/tekton-tutorial/tree/master/triggers)
 - [SSO configuration from xUnholy/k8s-gitops](https://github.com/xUnholy/k8s-gitops)
 - [Pre-commit config from k8s-at-home/flux-cluster-template](https://github.com/k8s-at-home/flux-cluster-template)
+- [Diátaxis technical documentation framework](https://diataxis.fr)
 
 Here is a list of the contributors who have helped to improve this project.
 Big shout-out to them!

docs/concepts/documentation.md

@@ -1,6 +1,7 @@
 # Documentation (this website)
 
-Documents can be viewed at <https://homelab.khuedoan.com>.
+The project uses the [Diátaxis](https://diataxis.fr) technical documentation framework.
+It can be viewed at <https://homelab.khuedoan.com>.
 
 ## Local development
 

docs/concepts/pxe-boot.md

@@ -1,4 +1,4 @@
-# Bare metal provisioning (PXE boot)
+# PXE boot
 
 ```mermaid
 flowchart TD

docs/concepts/secrets-management.md

@@ -1,5 +1,7 @@
 # Secrets management
 
+## 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.
@@ -26,7 +28,7 @@ flowchart TD
   ClusterSecretStore --> ExternalSecret
 ```
 
-## Generate random secret
+## Randomly generated secrets
 
 This is useful when you want to generate random secrets like admin password and store in Vault.
 
@@ -36,9 +38,9 @@ This is useful when you want to generate random secrets like admin password and
 --8<--
 ```
 
-## Pulling secrets from Vault to Kubernetes
+## How secrets are pulled from Vault to Kubernetes
 
-Commit and push an `ExternalSecret` object, for example:
+When you apply an `ExternalSecret` object, for example:
 
 ```yaml hl_lines="4 21-23"
 apiVersion: external-secrets.io/v1beta1

docs/concepts/tools-container.md

@@ -4,7 +4,7 @@ The tools container makes it easy to get all of the dependencies needed to inter
 
 ## How to open it
 
-You can use the default Docker wrapper, or use Nix if you have Nix installed
+You can use the default Docker wrapper, or use Nix if you have Nix installed:
 
 === "Docker"
 

docs/getting-started/install-pre-commit-hooks.md

@@ -1,7 +1,5 @@
 # Install pre-commit hooks
 
-> TODO: organize developer-focused documentation
-
 Git hook scripts are useful for identifying simple issues before commiting changes.
 
 Install [pre-commit](https://pre-commit.com/#install) first, one-liner for Arch users:
@@ -15,3 +13,5 @@ Then install git hook scripts:
 ```sh
 make git-hooks
 ```
+
+If you want to enable pre-commit on all repositories without enabling it manually, see [automatically enabling pre-commit on repositories](https://pre-commit.com/#automatically-enabling-pre-commit-on-repositories).

docs/getting-started/user-onboarding.md

@@ -0,0 +1,46 @@
+# User onboarding
+
+=== "For user"
+
+    ## Create user
+
+    Ask an admin to create your account, provide the following information:
+
+    - [ ] Full name (John Doe)
+    - [ ] Select a username (`johndoe`)
+    - [ ] Email address (`johndoe@example.com`)
+
+    ## Install companion apps
+
+    For all users:
+
+    - [ ] [Password manager](#recommended-password-managers)
+    - [ ] [Matrix chat client](https://matrix.org/clients) (optional, you can use the web version)
+
+    For technical users:
+
+    - [ ] [Docker](https://docs.docker.com/engine/install)
+    - [ ] [Lens](https://k8slens.dev) (optional, you can use the included `kubectl` or `k9s` command in the tools container)
+
+=== "For admin"
+
+    ## Create a new account
+
+    TODO
+
+    ## Send initial password
+
+    Choose one of the methods listed below to send the initial password to the user:
+
+    - Share via password manager (if supported)
+    - Encrypt the password file and send it via email or chat
+    - Simply write or print the password on a piece of paper
+
+    On the first login, the user will be required to update their password.
+
+## Appendix
+
+### Recommended password managers
+
+- [Bitwarden](https://bitwarden.com/download) (easy to use, but requires an online account)
+- [KeePassXC](https://keepassxc.org) (completely offline, but you'll need to sync manually)

docs/how-to-guides/alternate-dns-setup.md

@@ -1,4 +1,4 @@
-# Manual DNS setup
+# Alternate DNS setup
 
 !!! info
 

docs/how-to-guides/disable-dhcp-proxy-in-dnsmasq.md

@@ -1,13 +1,14 @@
-# Dnsmasq
+# Disable DHCP proxy in dnsmasq
 
 ## Overview
 
 Dnsmasq is used as either a DHCP server or DHCP proxy server for PXE metal provisioning.
 
 Proxy mode is enabled by default allowing the use of existing DHCP servers on the network.
-A good description on how DHCP Proxy works can be found on the related [FOG project wiki page](https://wiki.fogproject.org/wiki/index.php?title=ProxyDHCP_with_dnsmasq)
+A good description on how DHCP Proxy works can be found on the related [FOG project wiki page](https://wiki.fogproject.org/wiki/index.php?title=ProxyDHCP_with_dnsmasq).
 
-## Disabling Proxy Mode
+## Disabling Proxy mode
 
 Certain scenarios will require this project to use a DHCP server, such as an air-gap deployment or dedicated VLAN.
-To disable proxy mode thereby using dnsmasq as a DHCP server, modify `metal/roles/pxe_server/defaults/main.yml` and set `dhcp_proxy` to `false`
+
+To disable proxy mode thereby using dnsmasq as a DHCP server, modify `metal/roles/pxe_server/defaults/main.yml` and set `dhcp_proxy` to `false`.

docs/how-to-guides/troubleshooting/pxe-boot.md

@@ -1,4 +1,4 @@
-# Troubleshooting
+# PXE boot
 
 ## PXE server logs
 

docs/installation/post-installation.md

@@ -2,7 +2,7 @@
 
 ## Backup secrets
 
-Save the following files to a safe location (like a password manager):
+Save the following files to a safe location like a password manager (if you're using the sandbox, you can skip this step):
 
 - `~/.ssh/id_ed25519`
 - `~/.ssh/id_ed25519.pub`
@@ -10,8 +10,6 @@ Save the following files to a safe location (like a password manager):
 - `~/.terraform.d/credentials.tfrc.json`
 - `./external/terraform.tfvars`
 
-<!-- TODO - `./metal/root-password.txt` -->
-
 ## Admin credentials
 
 - ArgoCD:
@@ -25,7 +23,3 @@ Save the following files to a safe location (like a password manager):
 - Gitea:
     - Username: `gitea_admin`
     - Password: get from Vault
-
-## Next steps
-
-- [User onboarding](../../user-guide/onboarding.md)

docs/installation/production/configuration.md

@@ -1,6 +1,6 @@
 # Configuration
 
-Open the [tools container](../../runbooks/tools-container.md), which includes all the tools needed:
+Open the [tools container](../../concepts/tools-container.md), which includes all the tools needed:
 
 === "Docker"
 

docs/installation/production/deployment.md

@@ -27,4 +27,4 @@ Yes it's that simple!
     <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.
+you can read the [architecture document](../../reference/architecture/overview.md) while waiting for the deployment to complete.

docs/installation/production/external-resources.md

@@ -71,7 +71,7 @@ To avoid vendor lock-in, each external provider must have an equivalent alternat
     - Any other [Terraform backends](https://www.terraform.io/language/settings/backends)
 - Cloudflare DNS:
     - Update cert-manager and external-dns to use a different provider
-    - [Manual DNS setup](../../tutorials/manual-dns-setup.md)
+    - [Alternate DNS setup](../../how-to-guides/alternate-dns-setup.md)
 - Cloudflare Tunnel:
     - Use port forwarding if it's available
     - Create a small VPS in the cloud and utilize Wireguard and HAProxy to route traffic via it

docs/installation/production/prerequisites.md

@@ -40,7 +40,7 @@ Any modern `x86_64` computer(s) should work, you can use old PCs, laptops or ser
 | CPU        | 2 cores                                                                                                      | 4 cores                                                                                      |
 | RAM        | 8 GB                                                                                                         | 16 GB                                                                                        |
 | Hard drive | 128 GB                                                                                                       | 512 GB (depending on your storage usage, the base installation will not use more than 128GB) |
-| Node count | 1 (checkout the [single node cluster adjustments](../../tutorials/single-node-cluster-adjustments.md) tutorial) | 3 or more for high availability                                                              |
+| Node count | 1 (checkout the [single node cluster adjustments](../../how-to-guides/single-node-cluster-adjustments.md) tutorial) | 3 or more for high availability                                                              |
 
 Additional capabilities:
 
@@ -54,7 +54,7 @@ Additional capabilities:
 
 ## Domain
 
-Buying a domain is highly recommended, but if you don't have one, see [manual DNS setup](../../tutorials/manual-dns-setup.md).
+Buying a domain is highly recommended, but if you don't have one, see [alternate DNS setup](../../how-to-guides/alternate-dns-setup.md).
 
 ## BIOS setup
 

docs/installation/sandbox.md

@@ -2,17 +2,6 @@
 
 The sandbox is intended for trying out the homelab without any hardware or testing changes before applying them to the production environment.
 
-## Caveats compare to production environment
-
-The development cluster doesn't have the following features:
-
-- There is no valid domain name, hence no SSL certificates (some services require valid SSL certificates)
-- Only accessible on the host machine
-- No backup
-<!-- TODO more caveats here -->
-
-Please keep in mind that the development cluster may be unstable and things may break (it's for development after all).
-
 ## Prerequisites
 
 Host machine:
@@ -65,7 +54,7 @@ make
 
 The homepage should be available at <https://home.127-0-0-1.nip.io> (ignore the security warning because we don't have valid certificates).
 
-See [admin credentials](../production/post-installation/#admin-credentials) for default passwords.
+See [admin credentials](../post-installation/#admin-credentials) for default passwords.
 
 ## Clean up
 
@@ -74,3 +63,13 @@ Delete the cluster:
 ```sh
 k3d cluster delete homelab-dev
 ```
+
+## Caveats compare to production environment
+
+The development cluster doesn't have the following features:
+
+- There is no valid domain name, hence no SSL certificates (some services require valid SSL certificates)
+- Only accessible on the host machine
+- No backup
+
+Please keep in mind that the development cluster may be unstable and things may break (it's for development after all).

docs/reference/architecture/decision-records.md

@@ -0,0 +1,116 @@
+# Decision records
+
+??? Template
+
+    ## Description of the the change
+
+    **Context**
+
+    CHANGEME
+
+    **Decision**
+
+    CHANGEME
+
+    **Consequences**
+
+    - CHANGEME
+
+## Refactor the tools container from plain Dockerfile to [Nix](https://nixos.org)
+
+**Context**
+
+The previous implementation of the tools container is not reproducible, if someone builds it a few weeks after me, they will receive different versions of the tools.
+Also, if you change something in the tool list, everything will be downloaded again, with no caching.
+
+**Decision**
+
+Move to Nix shell with a Docker wrapper, in case Nix is not available (see commit `adbaf32`).
+
+**Consequences**
+
+- All versions are pinned
+- When you change the list of tools, rebuilding is much faster
+
+## Combine dhcpd and tftpd to dnsmasq in PXE server
+
+**Context**
+
+[Original proposal from @Bourne-ID](https://github.com/khuedoan/homelab/issues/70):
+
+> **Issue statement**
+>
+> The use of dhcpd is great for air-gap solutions where a new DHCP is required. However for some home networks which does not have the VLAN capability or for users who would like to use common router DHCP services, the use of DHCPD will cause duplicate DHCP servers and will result in potential network disruption, or will limit the ability to auto-provision the Metal stage of this project.
+>
+> **Proposed Solution: DHCP Proxy**
+>
+> Use DHCP Proxy services to add PXE features such as Next Server into this project. This allows for users to use the existing DHCP servers which may be locked down or incapable of using Next Server/PXE settings on their network to be able to auto-provision hardware through PXE (with certain common configurations, like static IP allocation or reduction in DHCP request ranges on the DHCP server)
+>
+> **Proposed Application: DNSMasq**
+>
+> DNSMasq in Proxy mode interoperates with existing DHCP servers over IPv4 to add features such as next-server, TFTP, etc. where such hardware is either locked or unconfigurable for such services. This would be an opt-in change, configurable through the pxe_server defaults file.
+>
+> **Proposed Target Audience**
+>
+> Users who either do not want to create their own VLAN or lack the hardware to configure such services. Users who want to use common router services for DHCP and have router access to configure static IP and/or DHCP allocation ranges.
+>
+> **Additional Risks with Proposed Change**
+>
+>   - Additional Surface Area for Break-Out Attacks: Originally this project is locked to its own DHCP/VLAN, so any break-outs should be contained accordingly. Using common home networks increases the surface area of break-out attacks if the deployment is compromised.
+>   - Mitigation: Enrolment into this change is opt in only.
+>
+> **Proposed Next Steps**
+>
+> 1. Trial/Adopt/Halt - A discussion with all or a decision by the project maintainers to identify if this change should exist in this project or live on a fork.
+> 2. Documentation (This is in flight in any situation).
+
+**Decision**
+
+Migrate to dnsmasq (see commit `f650c89`, thanks to [@Bourne-ID](https://github.com/Bourne-ID))
+
+**Consequences**
+
+- DHCP proxy is enabled by default because most people have a standard home network with existing DHCP server, but it can still be disabled to restore the previous behavior
+
+## Migrate documentation from [mdBook](https://rust-lang.github.io/mdBook) to [MkDocs](https://squidfunk.github.io/mkdocs-material)
+
+**Context**
+
+mdBook is very minimal and light weight, which I personally prefer.
+However, [Backstage TechDocs](https://backstage.io/docs/features/techdocs/techdocs-overview) which I plan to use currently only supports mkDocs.
+
+**Decision**
+
+Migrate documentation from mdBook to MkDocs (see commit `cd41343`).
+
+**Consequences**
+
+- We can no longer include only a portion of a file, see [facelessuser/pymdown-extensions#1462](https://github.com/facelessuser/pymdown-extensions/issues/1462).
+
+## Choosing the base OS
+
+**Context**
+
+I've tried several distributions, and each has advantages and disadvantages.
+Fedora has a good (enough) balance between stability and new features.
+
+Alternatives considered:
+
+- Fedora CoreOS (moved to Rocky in `7667254`):
+    - Pros: automatic and atomic upgrade, immutable, quick installation
+    - Cons: hard to run Ansible on (Python is not included)
+- CentOS/Rocky Linux (moved to Fedora in `022b816`):
+    - Pros: relatively stable (however we did encounter a breaking change [#63](https://github.com/khuedoan/homelab/issues/63), still not sure why)
+    - Cons: kernel and packages are too old
+- Debian: couldn't get it to work with PXE boot and Rocky Linux was sufficient so I didn't push any further
+- Cluster API (previous attempt in ` a8e4a85`, I hope to get this to work someday):
+    - Pros: control bare metal machines via Kubernetes API, open the possibility for autoscaling and autohealing
+    - Cons: doesn't support simple WoL and shutdown via SSH (or similar)
+
+**Decision**
+
+Use Fedora as the base OS.
+
+**Consequences**
+
+`¯\_(ツ)_/¯`

docs/tutorials/create-a-new-user-account.md

@@ -1,15 +0,0 @@
-# Create a new user account
-
-## Create a new account
-
-TODO
-
-## Send initial password
-
-Choose one of the methods listed below to send the initial password to the user:
-
-- Share via password manager (if supported)
-- Encrypt the password file and send it via email or chat
-- Simply write or print the password on a piece of paper
-
-On the first login, the user will be required to update their password.

docs/user-guide/onboarding.md

@@ -1,28 +0,0 @@
-# Onboarding
-
-## Create user
-
-Ask an admin to [create your account](../tutorials/create-a-new-user-account.md), provide the following information:
-
-- [ ] Full name
-- [ ] Select a username
-- [ ] Email address
-
-## Install companion apps
-
-For all users:
-
-- [ ] [Password manager](#recommended-password-managers)
-- [ ] [Matrix chat client](https://matrix.org/clients) (optional, you can use the web version)
-
-For technical users:
-
-- [ ] [Docker](https://docs.docker.com/engine/install)
-- [ ] [Lens](https://k8slens.dev) (optional, you can use the included `kubectl` or `k9s` command in the tools container)
-
-## Appendix
-
-### Recommended password managers
-
-- [Bitwarden](https://bitwarden.com/download) (easy to use, but requires an online account)
-- [KeePassXC](https://keepassxc.org) (completely offline, but you'll need to sync manually)

mkdocs.yml

@@ -43,33 +43,35 @@ nav:
       - installation/production/external-resources.md
       - installation/production/configuration.md
       - installation/production/deployment.md
-      - installation/production/post-installation.md
+    - installation/post-installation.md
-  - Architecture:
+  - Getting started:
-    - architecture/overview.md
+    - getting-started/user-onboarding.md
-    - architecture/bare-metal-provisioning.md
+    - getting-started/install-pre-commit-hooks.md
-    - architecture/secrets-management.md
+  - Concepts:
-    - architecture/networking.md
+    - concepts/documentation.md
-  - Tutorials:
+    - concepts/pxe-boot.md
-    - tutorials/manual-dns-setup.md
+    - concepts/secrets-management.md
-    - tutorials/create-a-new-user-account.md
+    - concepts/tools-container.md
-    - tutorials/expose-services-to-the-internet.md
+  - How-to guides:
-    - tutorials/use-both-github-and-gitea.md
+    - how-to-guides/alternate-dns-setup.md
-    - tutorials/add-or-remove-nodes.md
+    - how-to-guides/expose-services-to-the-internet.md
-    - tutorials/run-commands-on-multiple-nodes.md
+    - how-to-guides/use-both-github-and-gitea.md
-    - tutorials/single-node-cluster-adjustments.md
+    - how-to-guides/add-or-remove-nodes.md
-  - Runbooks:
+    - how-to-guides/run-commands-on-multiple-nodes.md
-    - runbooks/argocd.md
+    - how-to-guides/single-node-cluster-adjustments.md
-    - runbooks/cert-manager.md
+    - how-to-guides/disable-dhcp-proxy-in-dnsmasq.md
-    - runbooks/dnsmasq.md
+    - Troubleshooting:
-    - runbooks/documentation.md
+      - how-to-guides/troubleshooting/argocd.md
-    - runbooks/gitea.md
+      - how-to-guides/troubleshooting/cert-manager.md
-    - runbooks/longhorn.md
+      - how-to-guides/troubleshooting/gitea.md
-    - runbooks/tools-container.md
+      - how-to-guides/troubleshooting/longhorn.md
-    - runbooks/vault.md
+      - how-to-guides/troubleshooting/pxe-boot.md
-  - troubleshooting.md
+      - how-to-guides/troubleshooting/vault.md
-  - User guide:
-    - user-guide/onboarding.md
   - Reference:
+    - Architecture:
+      - reference/architecture/overview.md
+      - reference/architecture/networking.md
+      - reference/architecture/decision-records.md
     - reference/license.md
     - reference/changelog.md
     - reference/roadmap.md