docs: add more docs and move some section from README to docs

README.md

@@ -44,89 +44,22 @@
 
 _This list might be outdated, please let me know if I forgot to update it._
 
-### Provisioning flow
-
-<!-- ![Provisioning flow](https://khuedoan.github.io/homelab/diagrams/provisioning_flow.jpg) -->
-
-Everything is automated, I just need to run a single `make` command and it will:
-
-- Build the `./metal` layer:
-  - Create an ephemeral, stateless PXE server
-  - Install Linux on all servers in parallel
-  - Build a Kubernetes cluster (based on k3s)
-- Build the `./bootstrap` layer:
-  - Install ArgoCD
-  - Install ApplicationSet to manage other layers (and also manage itself)
-
-From now on, ArgoCD will do the rest:
-
-- Build the `./system` layer (storage, networking, monitoring, etc)
-- Build the `./platform` layer (Gitea, Vault, SSO, etc)
-- Build the `./apps` layer: (Syncthing, Jellyfin, etc)
-
-Please visit the [Provisioning flow document](https://khuedoan.github.io/homelab/deployment/provisioning_flow.html) to learn more.
-
 ## Get Started
 
-### Harware requirements
+- [Try it out on a VM](https://docs.khuedoan.com/homelab) without any hardware
-
+- [Deploy on real hardware](https://docs.khuedoan.com/homelab) for real workload
-Any modern `x86_64` computer(s) should work, you can use old PCs, laptops or servers.
-A total of 3 or more nodes is recommended for high availability.
-
-To view the detailed requirements, please visit the [Hareware requirements document](https://khuedoan.github.io/homelab/deployment/hardware_requirements.html).
-
-### Prerequisite
-
-For the controller (your laptop or desktop):
-
-- SSH keys in `~/.ssh/{id_ed25519,id_ed25519.pub}` (you can generate it with `ssh-keygen -t ed25519`)
-- Docker with `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)
-
-For bare metal nodes:
-
-- PXE IPv4 enabled
-- Wake-on-LAN enabled and boot to network mode by default if turned on via Wake-on-LAN
-- Secure boot disabled (optional, depending on the OS)
-- Note their MAC addresses
-
-To view the detailed instruction, please visit the [Prerequisite document](https://khuedoan.github.io/homelab/deployment/prerequisite.html).
-
-### Configurations
-
-Change these configuration files to match your hardware and network setup:
-
-- [Bare metal nodes settings](./metal/hosts.yml) (IP, MAC...)
-- [OS settings](./metal/group_vars/all.yml) (PXE, network...)
-
-To view the detailed instruction, please visit the [Configuration document](https://khuedoan.github.io/homelab/deployment/configuration.html).
-
-### Build
-
-You can install all the tools manually, or you can use the convenience tools container:
-
-```sh
-make tools
-```
-
-Then build the homelab:
-
-```sh
-make
-```
-
-If you encounter any issue, please visit [Trouble shooting guide](https://khuedoan.github.io/homelab/troubleshooting/README.html)
 
 ## Roadmap
 
-See [roadmap](https://khuedoan.github.io/homelab/roadmap.html) and [open issues](https://github.com/khuedoan/homelab/issues) for a list of proposed features and known issues.
+See [roadmap](https://docs.khuedoan.com/homelab/roadmap.html) and [open issues](https://github.com/khuedoan/homelab/issues) for a list of proposed features and known issues.
 
 ## Contributing
 
-Any contributions you make are greatly appreciated (feature, bug fixes, documentation, grammar or typo fix...).
+Any contributions you make are greatly appreciated (feature, bug fix, documentation, grammar or typo fix...).
 
 ## License
 
-Distributed under the GPLv3 License. See `LICENSE` for more information.
+Distributed under the GPLv3 License. See [LICENSE](./LICENSE.md) for more information.
 
 ## Acknowledgements
 

docs/SUMMARY.md

@@ -1,24 +1,23 @@
 # Summary
 
-[Table of contents](./SUMMARY.md)
-
----
-
 - [Introduction](introduction.md)
+- [Try on a VM](try_on_a_vm.md)
 - [Deployment](./deployment/README.md)
   - [Provisioning flow](./deployment/provisioning_flow.md)
-  - [Harware requirements](./deployment/hardware_requirements.md)
   - [Prerequisites](./deployment/prerequisites.md)
   - [Configuration](./deployment/configuration.md)
   - [Deploy the homelab](./deployment/deployment.md)
   - [DNS setup](./deployment/dns.md)
 - [Troubleshooting](./troubleshooting/README.md)
   - [PXE boot](./troubleshooting/pxe_boot.md)
+  - [ArgoCD]()
 - [Reference](./reference/README.md)
-  - [Architecture](./reference/architecture.md)
+  - [Architecture]()
   - [FAQ](./reference/faq.md)
+  - [Contributors](./reference/contributors.md)
 
 ---
 
 - [Changelog](./changelog.md)
 - [Roadmap](./roadmap.md)
+- [License](./license.md)

docs/deployment/README.md

@@ -1,3 +1,10 @@
 # Deployment
 
-TODO
+In this section you will learn how to:
+
+- Prepare your hardware
+- Update the configurations to fit your needs (hardware info, domain name...)
+- Build the cluster and bootstrap it
+- Perform some addtional steps depending on your set up (DNS, external secrets...)
+
+If you encounter any issue, please see the [Troubleshooting](../troubleshooting) section.

docs/deployment/configuration.md

@@ -1,3 +1,21 @@
 # Configuration
 
-TODO
+## SSH keys
+
+> Skip this step if you already have an Ed25519 key pair
+
+Generate SSH private key and public key on the controller (your laptop or desktop):
+
+```sh
+ssh-keygen -t ed25519
+```
+
+## Update variables and parameters
+
+This project follows GitOps practice, the git repository is the source of truth for you homelab setup, so you will need to [fork this repository](https://github.com/khuedoan/homelab) and update these config files based on those information:
+
+- [ ] `metal/inventories/prod.ini`
+- [ ] `metal/group_vars/all.yml`
+- [ ] TODO git repository config in `bootstrap/...`
+- [ ] TODO single place for Ingress domain
+- [ ] TODO single place for docs link config

docs/deployment/deployment.md

@@ -1,3 +1,17 @@
 # Deploy the homelab
 
-TODO
+> It will take a while to build the tools container and download Rocky Linux ISO on the first time
+
+Open the tools container, which includes all the tools needed:
+
+```sh
+make tools
+```
+
+Build the lab:
+
+```sh
+make
+```
+
+Yes it's that simple! Continue to the next section to update your DNS.

docs/deployment/dns.md

@@ -1,5 +1,7 @@
 # DNS setup
 
+Because everyone DNS setup is different, DNS automation is not in the scope of the project.
+
 Some options for DNS config:
 
 - Change the DNS config in your router
@@ -24,7 +26,7 @@ resource "cloudflare_record" "homelab_records" {
   zone_id = cloudflare_zone.khuedoan_com.id
   type    = "A"
   name    = each.key
-  value   = "192.168.1.150"
+  value   = "192.168.1.150" # NGINX LoadBalancer IP
   ttl     = 1 # Auto
 }
 ```

docs/deployment/hardware_requirements.md

@@ -1,28 +0,0 @@
-# Hardware requirements
-
-## Initial controller
-
-> The initial controller is the machine used to bootstrap the cluster.
-
-- Any machine that can run Linux and Docker should work (I'm using my laptop).
-- Wired Ethernet connection is prefered (Wifi is untested, please let me know if it works)
-
-## Server hardware
-
-> This is the requirements for _each_ node
-
-- Minimum:
-  - 1 node
-  - At least 2 cores
-  - At least 8GB of RAM
-  - At least 128GB of hard drive
-
-- Recommended:
-  - 3 nodes or more for high availability
-  - 4 cores
-  - 16GB of RAM
-  - 512GB of hard drive (depending on your storage usage, the base installation will not use more than 128GB)
-
-- Ability to boot from the network (PXE boot)
-- Wake-on-LAN capability, used to wake the machines up automatically without physically touching the power button
-- Connected to the same **wired** network with the initial controller (for DHCP broadcast)

docs/deployment/prerequisites.md

@@ -1,5 +1,36 @@
 # Prerequisites
 
+## 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
+
+- 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)
+
+### Servers
+
+Any modern `x86_64` computer(s) should work, you can use old PCs, laptops or servers.
+
+> 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 | 3 or more for high availability |
+
+Additional capabilities:
+
+- Ability to boot from the network (PXE boot)
+- Wake-on-LAN capability, used to wake the machines up automatically without physically touching the power button
+
+### 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)
+- You have the access to change DNS config (on your router or at your domain registrar)
+
 ## BIOS setup
 
 > You need to do it once per machine if the default config is not sufficent,
@@ -35,21 +66,9 @@ Below is my BIOS setup, your motherboard may have a different name for the optio
 }
 ```
 
-## Update config files
+## Gather the information
-
-Gather the following information:
 
 - [ ] MAC address for each machine
 - [ ] OS disk name (for example `/dev/sda`)
 - [ ] Network interface name (for example `eth0`)
 - [ ] Choose a static IP address for each machine (just the desired address, we don't set anything up yet)
-
-[Fork this repo](https://github.com/khuedoan/homelab) and update these config files based on those information:
-
-- [ ] `metal/hosts.yml`
-- [ ] `metal/group_vars/all.yml`
-- [ ] TODO git config in `bootstrap/...`
-- [ ] TODO single place for Ingress domain
-- [ ] (Optional) TODO single place for docs link config
-
-TODO single place for all config, maybe a `./config` directory with some symlinks?

docs/deployment/provisioning_flow.md

@@ -2,4 +2,18 @@
 
 ![Provisioning flow](../diagrams/provisioning_flow.jpg)
 
-TODO
+Everything is automated, after you edit the configuration files, you just need to run a single `make` command and it will:
+
+- Build the `./metal` layer:
+  - Create an ephemeral, stateless PXE server
+  - Install Linux on all servers in parallel
+  - Build a Kubernetes cluster (based on k3s)
+- Build the `./bootstrap` layer:
+  - Install ArgoCD
+  - Install ApplicationSet to manage other layers (and also manage itself)
+
+From now on, ArgoCD will do the rest:
+
+- Build the `./system` layer (storage, networking, monitoring, etc)
+- Build the `./platform` layer (Gitea, Vault, SSO, etc)
+- Build the `./apps` layer: (Syncthing, Jellyfin, etc)

docs/license.md

@@ -0,0 +1 @@
+{{#include ../LICENSE.md}}

docs/reference/architecture.md

@@ -1,3 +0,0 @@
-# Architecture
-
-TODO

docs/reference/contributors.md

@@ -0,0 +1,7 @@
+# Contributors
+
+Here is a list of the contributors who have helped improving my homelab. Big shout-out to them!
+
+- None, you can be the first one ;)
+
+If you feel you're missing from this list, feel free to add yourself in a PR.

docs/reference/faq.md

@@ -8,9 +8,3 @@ No, and it's the beauty of this set up. You start from scratch (empty hard drive
 
 No, the ephemeral PXE server is stateless, after Linux is installed on your servers you can shut it down (or not, ideally you don't even need to care about its existence).
 The Ansible set up in `./metal` is idempotent and will start the PXE server if needed.
-
-## Where Terraform state is stored?
-
-In a Docker container on the first node, which was created by the `./metal` layer (it's not HA _yet_).
-
-However I'm experimenting with Cluster API, remove the needs for a Terraform state storage.

docs/troubleshooting/README.md

@@ -1,3 +1,3 @@
 # Troubleshooting
 
-TODO
+This section contains some common issues and solutions. If you find any issues that are not listed here, please send me a PR.

docs/try_on_a_vm.md

@@ -0,0 +1,44 @@
+# Try on a VM
+
+## Prerequisites
+
+Install the following packages:
+
+- `virtualbox`
+- `vagrant`
+
+## Build
+
+Follow the [configuration guide](./deployment/configuration.md), then build the cluster and bootstrap it:
+
+```sh
+make -C metal dev
+make bootstrap
+```
+
+Get the Ingress addresses and IPs:
+
+```sh
+export KUBECONFIG=$PWD/metal/kubeconfig.yaml
+kubectl get ingress -A
+```
+
+Then update your `/etc/hosts` or your router DNS config based on the output:
+
+```
+192.168.1.150 argocd.mydomain.com
+192.168.1.150 git.mydomain.com
+192.168.1.150 jellyfin.mydomain.com
+# etc.
+```
+
+## Clean up
+
+Shut down the VM:
+
+```sh
+cd metal
+vagrant destroy -f
+```
+
+Then clean up your router config or `/etc/hosts` file from the previous step