docs: add more details for config instructions

docs/src/deployment/configuration.md

@@ -10,12 +10,50 @@ Generate SSH private key and public key on the controller (your laptop or deskto
 ssh-keygen -t ed25519
 ```
 
-## Update variables and parameters
+## Fork this repository
 
-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:
+Because this repository applies GitOps practices, this git repository is the source of truth for my homelab, so you'll need to folk it to make it yours.
 
-- [ ] `metal/inventories/prod.ini`
+After forking it, clone and replace the reference to my repository with yours (without `https://`):
-- [ ] `metal/group_vars/all.yml`
+
-- [ ] TODO git repository config in `bootstrap/...`
+```sh
-- [ ] TODO single place for Ingress domain
+./scripts/replace-gitops-repo "gitservicelikegithub.com/yourname/homelab"
-- [ ] TODO single place for docs link config
+```
+
+Then commit and push the changes.
+
+## Server list
+
+Edit the following file and replace the MAC addresses with the one on your servers.
+The IP addresses are the desired ones, since your servers have no operating system installed yet.
+
+> If you're trying it out on the dev VM, replace use the `dev.ini` instead of the `prod.ini` file
+
+```ini
+; metal/inventories/prod.ini
+{{#include ../../../metal/inventories/prod.ini:5:}}
+```
+
+## Server hardware info
+
+> Skip this step if you're trying out the dev VM
+
+Change the following parameters based on your hardware.
+
+```yaml
+# metal/group_vars/all.yaml
+{{#include ../../../metal/group_vars/all.yml:6:}}
+```
+
+- 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`
+
+## Update Ingresses to point to your domain
+
+My domain is `khuedoan.com`, run the following command to replace it with yours:
+
+```sh
+./scripts/replace-domain "yourdomain.com"
+```
+
+Commit and push the changes.

docs/src/deployment/prerequisites.md

@@ -31,6 +31,10 @@ Additional capabilities:
 - 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)
 
+## 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).
+
 ## BIOS setup
 
 > You need to do it once per machine if the default config is not sufficent,
@@ -66,7 +70,7 @@ Below is my BIOS setup, your motherboard may have a different name for the optio
 }
 ```
 
-## Gather the information
+## Gather information
 
 - [ ] MAC address for each machine
 - [ ] OS disk name (for example `/dev/sda`)

docs/src/try_on_a_vm.md

@@ -9,7 +9,14 @@ Install the following packages:
 
 ## Build
 
-Follow the [configuration guide](./deployment/configuration.md), then build the cluster and bootstrap it:
+Change the IP prefix in the Vagrant config to match your LAN setup, for example my IP prefix is `192.168.1.`:
+
+```ruby
+# metal/Vagrantfile
+{{#include ../../metal/Vagrantfile:4}}
+```
+
+Follow the remaining steps in the [configuration guide](./deployment/configuration.md), then build the cluster and bootstrap it:
 
 ```sh
 make -C metal dev

metal/Vagrantfile

@@ -1,5 +1,7 @@
+# require 'ipaddr' # TODO dynamic IP based on inventory
 require 'yaml'
 
+ip_prefix = '192.168.1.'
 group_vars = YAML.load_file('./group_vars/all.yml')
 
 Vagrant.configure("2") do |config|
@@ -9,7 +11,7 @@ Vagrant.configure("2") do |config|
 
   (0..(node_count-1)).each do |i|
     config.vm.define "dev#{i}" do |dev|
-      dev.vm.network "public_network", ip: "192.168.1.#{200+i+1}"
+      dev.vm.network "public_network", ip: "#{ip_prefix}#{200+i+1}"
       dev.vm.hostname = "dev#{i}"
       dev.vm.disk :disk, size: "128GB", primary: true
     end

metal/group_vars/all.yml

@@ -1,7 +1,7 @@
 ansible_user: root
 ansible_ssh_private_key_file: ~/.ssh/id_ed25519
+ssh_public_key: "{{lookup('file', '~/.ssh/id_ed25519.pub') }}"
+dns_server: "8.8.8.8"
 
 disk: "sda"
-dns_server: "8.8.8.8"
 network_interface: "eno1"
-ssh_public_key: "{{lookup('file', '~/.ssh/id_ed25519.pub') }}"