refactor(docs): migrate to mkdocs (#68)

* refactor(docs): migrate to mkdocs * More markdown * Admonitions
khuedoan · Jul 6, 2022 · cd41343 · cd41343
1 parent a7f9150
commit cd41343
Show file tree

Hide file tree

Showing 51 changed files with 797 additions and 745 deletions.
diff --git a/Makefile b/Makefile
@@ -34,3 +34,12 @@ docs:
 dev:
 	make -C metal cluster env=dev
 	make -C bootstrap
+
+docs:
+	docker run \
+		--rm \
+		--interactive \
+		--tty \
+		--publish 8000:8000 \
+		--volume $(shell pwd):/docs \
+		squidfunk/mkdocs-material
diff --git a/README.md b/README.md
diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/README.md b/docs/README.md
diff --git a/docs/book.toml b/docs/book.toml
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,3 @@
+--8<--
+README.md
+--8<--
diff --git a/docs/src/try-locally.md → docs/installation/development.md b/docs/src/try-locally.md → docs/installation/development.md
@@ -1,4 +1,4 @@
-# Try locally
+# Development environment
 
 ## Caveats compare to production environment
 
@@ -17,15 +17,15 @@ Host machine:
 
 - OS: Linux (Windows and macOS will not work due to networking limitations, you can use a Linux VM)
 - Recommended hardware specifications:
-  - CPU: 4 cores
-  - RAM: 16 GiB
+    - CPU: 4 cores
+    - RAM: 16 GiB
 
 Install the following packages:
 
 - `docker`
 - `make`
 
-Clone the repository (follow the [configuration guide](./deployment/configuration.md) if you want to customize it):
+Clone the repository and checkout the development branch:
 
 ```sh
 git clone https://github.com/khuedoan/homelab

diff --git a/docs/installation/production/configuration.md b/docs/installation/production/configuration.md
@@ -0,0 +1,44 @@
+# Configuration
+
+Open the tools container if you haven't already:
+
+```sh
+make tools
+```
+
+!!! note
+
+     It will take a while to build the tools container on the first time
+
+Run the following script to configure the homelab:
+
+```sh
+make configure
+```
+
+!!! example
+
+    <!-- TODO update example input -->
+
+    ```
+    Text editor (nvim):
+    Enter seed repo (github.com/khuedoan/homelab): github.com/example/homelab
+    Enter your domain (khuedoan.com): example.com
+    ```
+
+It will prompt you to edit the inventory:
+
+- IP address: the desired one, not the current one, since your servers have no operating system installed yet
+- Disk: based on `/dev/$DISK`, in my case it's `sda`, but yours can be `sdb`, `nvme0n1`...
+- Network interface: usually it's `eth0`, mine is `eno1`
+- MAC address: the **lowercase, colon separated** MAC address of the above network interface
+
+!!! example
+
+    ```yaml title="metal/inventories/prod.yml"
+    --8<--
+    metal/inventories/prod.yml
+    --8<--
+    ```
+
+At the end it will show what has changed. After examining the diff, commit and push the changes.
diff --git a/docs/installation/production/deployment.md b/docs/installation/production/deployment.md
@@ -0,0 +1,21 @@
+# Deployment
+
+Open the tools container, which includes all the tools needed:
+
+```sh
+make tools
+```
+
+Build the lab:
+
+```sh
+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.
diff --git a/external/README.md → ...allation/production/external-resources.md b/external/README.md → ...allation/production/external-resources.md
@@ -1,8 +1,8 @@
 # External resources
 
-**WIP documents**
+!!! info
 
-> These resources are optional, the homelab still works without them but will lack some features like trusted certificates and offsite backup
+    These resources are optional, the homelab still works without them but will lack some features like trusted certificates and offsite backup
 
 Although I try to keep the amount of external resources to the minimum, there's still need for a few of them.
 Below is a list of external resources and why we need them (also see some [alternatives](#alternatives) below).
@@ -12,15 +12,17 @@ Below is a list of external resources and why we need them (also see some [alter
 | Terraform Cloud | Workspace  | Terraform state backend                                                                                     |
 | Cloudflare      | DNS        | DNS and [DNS-01 challenge](https://letsencrypt.org/docs/challenge-types/#dns-01-challenge) for certificates |
 | Cloudflare      | Tunnel     | Public services to the internet without port-forwarding                                                     |
-| Minio           | Bucket     | Onsite backup                                                                                               |
-| AWS             | S3 Glacier | Offsite backup                                                                                              |
+<!-- | Minio           | Bucket     | Onsite backup                                                                                               | -->
+<!-- | AWS             | S3 Glacier | Offsite backup                                                                                              | -->
 
 This layer will:
 
 - Create external resources
 - Add external secrets to namespaces
 
-## Prerequisites
+## Create credentials
+
+You'll be asked to provide these credentials on first build.
 
 ### Create Terraform workspace
 
@@ -52,25 +54,17 @@ If you decide to use a [different Terraform backend](https://www.terraform.io/la
 <!-- └── Is in - 117.xxx.xxx.xxx, 2402:xxx:xxx:xxx:xxx:xxx:xxx:xxx -->
 <!-- ``` -->
 
-### Create Minio keys
-
-TODO: skip this for now
-
-### Create AWS API key
-
-TODO: skip this for now
+<!-- ### Create Minio keys -->
 
-## Deploy
+<!-- TODO: skip this for now -->
 
-Apply Terraform (you will be prompted to log in to Terraform Cloud and enter API keys from the previous steps):
+<!-- ### Create AWS API key -->
 
-```sh
-# From the project root
-make external
-```
+<!-- TODO: skip this for now -->
 
 ## Alternatives
 
 - Terraform Cloud: any other [Terraform backends](https://www.terraform.io/language/settings/backends)
+- Cloudflare DNS: see [manual DNS setup](../../tutorials/manual-dns-setup.md)
 - Cloudflare Tunnel: you can create a small VPS in the cloud and utilize Wireguard and HAProxy to route traffic via it, or just use simple port-forwarding if it's available (see also [awesome tunneling](https://github.com/anderspitman/awesome-tunneling))
-- Minio and S3 Glacier: any S3 compatible object storage, such as Backblaze B2, Minio...
+<!-- - Minio and S3 Glacier: any S3 compatible object storage, such as Backblaze B2, Minio... -->
diff --git a/docs/src/deployment/post-installation.md → ...tallation/production/post-installation.md b/docs/src/deployment/post-installation.md → ...tallation/production/post-installation.md
@@ -14,4 +14,4 @@ Save the following files to a safe location (like a password manager):
 
 ## Next steps
 
-TODO
+- [User onboarding](../../user-guide/onboarding.md)
diff --git a/docs/src/deployment/prerequisites.md → .../installation/production/prerequisites.md b/docs/src/deployment/prerequisites.md → .../installation/production/prerequisites.md
@@ -1,25 +1,46 @@
 # Prerequisites
 
+## Fork this repository
+
+Because [this project](https://github.com/khuedoan/homelab) applies GitOps practices,
+it's the source of truth for _my_ homelab, so you'll need to fork it to make it yours:
+
+[:fontawesome-solid-code-fork: Fork khuedoan/homelab](https://github.com/khuedoan/homelab/fork){ .md-button }
+
+By using this project you agree to [the license](/license).
+
+
+!!! summary "License TL;DR"
+
+     - This project is free to use for any purpose, but it comes with no warranty
+     - You must use the same [GPLv3 license](https://www.gnu.org/licenses/gpl-3.0.en.html)  in `LICENSE.md`
+     - You must keep the copy right notice and/or include an acknowledgement
+     - Your project must remain open-source
+
 ## Hardware requirements
 
 ### Initial controller
 
-> The initial controller is the machine used to bootstrap the cluster, we only need it once, you can use your laptop or desktop
+!!! info
+
+    The initial controller is the machine used to bootstrap the cluster, we only need it once, you can use your laptop or desktop
 
-- Any machine that can run Docker with the `host` networking driver ([which means only Docker on Linux hosts](https://docs.docker.com/network/host/), you can use a Linux virtual machine with bridged networking if you're on macOS or Windows)
+- A Linux machine that can run Docker (because the `host` networking driver used for PXE boot [only supports Linux](https://docs.docker.com/network/host/), you can use a Linux virtual machine with bridged networking if you're on macOS or Windows).
 
 ### Servers
 
 Any modern `x86_64` computer(s) should work, you can use old PCs, laptops or servers.
 
-> This is the requirements for _each_ node
+!!! info
+
+    This is the requirements for _each_ node
 
 | Component  | Minimum                                                                                                      | Recommended                                                                                  |
 | :--        | :--                                                                                                          | :--                                                                                          |
 | 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](../../tutorials/single-node-cluster-adjustments.md) tutorial) | 3 or more for high availability                                                              |
 
 Additional capabilities:
 
@@ -28,18 +49,20 @@ Additional capabilities:
 
 ### Network setup
 
-- All servers must be connected to the same **wired** network with the initial controller (Wifi is untested, please let me know if it works)
+- All servers must be connected to the same **wired** network with the initial controller
 - You have the access to change DNS config (on your router or at your domain registrar)
 
 ## Domain
 
-Buying a domain is highly recommended, but if you don't have one, you can also update your router config and point [`*.home.arpa`](https://datatracker.ietf.org/doc/html/rfc8375) to the load balancer (more on that later).
+Buying a domain is highly recommended, but if you don't have one, see [manual DNS setup](../../tutorials/manual-dns-setup.md).
 
 ## BIOS setup
 
-> You need to do it once per machine if the default config is not sufficent,
-> usually for consumer hardware this can not be automated
-> (it requires something like [IPMI](https://en.wikipedia.org/wiki/Intelligent_Platform_Management_Interface) to automate).
+!!! info
+
+    You need to do it once per machine if the default config is not sufficent,
+    usually for consumer hardware this can not be automated
+    (it requires something like [IPMI](https://en.wikipedia.org/wiki/Intelligent_Platform_Management_Interface) to automate).
 
 Common settings:
 
@@ -52,24 +75,26 @@ Boot order options (select one, each has their pros and cons):
 1. Only boot from the network if no operating system found: works on most hardware but you need to manually wipe your hard drive or delete the existing boot record for the current OS
 2. Prefer booting from the network if turned on via WoL: more convenience but your BIOS must support it, and you must test it throughly to ensure you don't accidentally wipe your servers
 
-Below is my BIOS setup for reference. Your motherboard may have a different name for the options, so you'll need to adapt it to your hardware.
-
-```yaml
-Devices:
-  NetworkSetup:
-    PXEIPv4: true
-    PXEIPv6: false
-Advanced:
-  CPUSetup:
-    VT-d: true
-Power:
-  AutomaticPowerOn:
-    WoL: Automatic  # Use network boot if Wake-on-LAN
-Security:
-  SecureBoot: false
-Startup:
-  CSM: false
-```
+!!! example
+
+    Below is my BIOS setup for reference. Your motherboard may have a different name for the options, so you'll need to adapt it to your hardware.
+
+    ```yaml
+    Devices:
+      NetworkSetup:
+        PXEIPv4: true
+        PXEIPv6: false
+    Advanced:
+      CPUSetup:
+        VT-d: true
+    Power:
+      AutomaticPowerOn:
+        WoL: Automatic  # Use network boot if Wake-on-LAN
+    Security:
+      SecureBoot: false
+    Startup:
+      CSM: false
+    ```
 
 ## Gather information