mirrors/khuedoan-homelab
1
0
Fork 0
mirror of https://github.com/khuedoan/homelab.git synced 2024-12-23 01:24:36 +07:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Khue Doan 2021-11-28 12:12:53 +07:00
parent 7660a5734b
commit da5138dac0
15 changed files with 155 additions and 134 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
README.md
View File

@ -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
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)
- [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
## 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

11
docs/SUMMARY.md
View File

@ -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)

9
docs/deployment/README.md
View File

@ -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.

20
docs/deployment/configuration.md
View File

@ -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

16
docs/deployment/deployment.md
View File

@ -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.

4
docs/deployment/dns.md
View File

@ -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
}
```

28
docs/deployment/hardware_requirements.md
View File

@ -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)

45
docs/deployment/prerequisites.md
View File

@ -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 following information:
## Gather the 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?

16
docs/deployment/provisioning_flow.md
View File

@ -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)

1
docs/license.md Normal file
View File

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

3
docs/reference/architecture.md
View File

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

7
docs/reference/contributors.md Normal file
View File

@ -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.

6
docs/reference/faq.md
View File

@ -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.

2
docs/troubleshooting/README.md
View File

@ -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.

44
docs/try_on_a_vm.md Normal file
View File

@ -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