diff --git a/Makefile b/Makefile index a327c682..82e36901 100644 --- 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 index 31e683f8..6176f994 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,7 @@ -
- # Khue's Homelab - +**[Features](#features) • [Get Started](#get-started) • [Documentation](https://homelab.khuedoan.com)** -[![chat](https://img.shields.io/matrix/homelab:matrix.khuedoan.com?style=flat-square&logo=matrix&logoColor=white&label=chat)](https://matrix.to/#/#homelab:matrix.khuedoan.com) [![tag](https://img.shields.io/github/v/tag/khuedoan/homelab?style=flat-square&logo=semver&logoColor=white)](https://github.com/khuedoan/homelab/tags) [![document](https://img.shields.io/website?label=document&logo=gitbook&logoColor=white&style=flat-square&url=https%3A%2F%2Fhomelab.khuedoan.com)](https://homelab.khuedoan.com) [![license](https://img.shields.io/github/license/khuedoan/homelab?style=flat-square&logo=gnu&logoColor=white)](https://www.gnu.org/licenses/gpl-3.0.html) @@ -13,33 +10,34 @@ This project utilizes [Infrastructure as Code](https://en.wikipedia.org/wiki/Infrastructure_as_code) and [GitOps](https://www.weave.works/technologies/gitops) to automate provisioning, operating, and updating self-hosted services in my homelab. It can be used as a highly customizable framework to build your own homelab. - - -Current status: **ALPHA** - -
+> **What is a homelab?** +> +> Homelab is a laboratory at home where you can self-host, experiment with new technologies, practice for certifications, and so on. +> For more information about homelab in general, see the [r/homelab introduction](https://www.reddit.com/r/homelab/wiki/introduction). ## Overview -This section provides a high level overview of the project. -For further information, please see the [documentation](https://homelab.khuedoan.com). +Project status: **ALPHA** + +This project is still in the experimental stage, and I don't use anything critical on it. +Expect breaking changes that may require a complete redeployment. +A proper upgrade path is planned for the stable release. +More information can be found in [the roadmap](#roadmap) below. ### Hardware ![Hardware](https://user-images.githubusercontent.com/27996771/98970963-25137200-2543-11eb-8f2d-f9a2d45756ef.JPG) - 4 × NEC SFF `PC-MK26ECZDR` (Japanese version of the ThinkCentre M700): - - CPU: `Intel Core i5-6600T @ 2.70GHz` - - RAM: `16GB` - - SSD: `128GB` + - CPU: `Intel Core i5-6600T @ 2.70GHz` + - RAM: `16GB` + - SSD: `128GB` - TP-Link `TL-SG108` switch: - - Ports: `8` - - Speed: `1000Mbps` + - Ports: `8` + - Speed: `1000Mbps` ### Features -Project status: **Alpha** (see [roadmap](#roadmap) below) - - [x] Common applications: Gitea, Seafile, Jellyfin, Paperless... - [x] Automated bare metal provisioning with PXE boot - [x] Automated Kubernetes installation and management @@ -58,198 +56,172 @@ Project status: **Alpha** (see [roadmap](#roadmap) below) - [ ] Automated offsite backups 🚧 - [ ] Single sign-on 🚧 -Some demo videos and screenshots are shown here. -They can't capture all of the project's features, but they are sufficient to get a concept of it. +Some demo videos and screenshots are shown here (click to enlarge). +They can't capture all the project's features, but they are sufficient to get a concept of it. -| [![Deployment](https://asciinema.org/a/xkBRkwC6e9RAzVuMDXH3nGHp7.svg)](https://asciinema.org/a/xkBRkwC6e9RAzVuMDXH3nGHp7) | -| :--: | -| Deploy with a single command (after updating the config files of course) | +| [![][screenshot-01]](https://asciinema.org/a/xkBRkwC6e9RAzVuMDXH3nGHp7) | [![][screenshot-02]](https://www.youtube.com/watch?v=y-d7btNNAT8) | +| :--: | :--: | +| Deploy with a single command (after updating the configuration files) | PXE boot | +| [![][screenshot-03]][screenshot-03] | [![][screenshot-04]][screenshot-04] | +| Homepage with Ingress discovery powered by [Hajimari](https://github.com/toboshii/hajimari) | Monitoring dashboard powered by [Grafana](https://grafana.com/) | +| [![][screenshot-05]][screenshot-05] | [![][screenshot-06]][screenshot-06] | +| Git server powered by [Gitea](https://gitea.io/en-us/) | [Matrix](https://matrix.org/) chat server | +| [![][screenshot-07]][screenshot-07] | [![][screenshot-08]][screenshot-08] | +| Continuous integration with [Tekton](https://tekton.dev/) | Continuous deployment with [ArgoCD](https://argoproj.github.io/cd/) | +| [![][screenshot-09]][screenshot-09] | [![][screenshot-10]][screenshot-10] | +| Cluster management using [Lens](https://k8slens.dev/) | Secret management with [Vault](https://www.vaultproject.io/) | -| [![PXE boot](https://user-images.githubusercontent.com/27996771/157303477-df2e7410-8f02-4648-a86c-71e6b7e89e35.png)](https://www.youtube.com/watch?v=y-d7btNNAT8) | -| :--: | -| PXE boot | - -| ![](https://user-images.githubusercontent.com/27996771/149445807-0f869eb7-d8f5-4fef-ab97-ac281df91a06.png) | -| :--: | -| Homepage with Ingress discovery powered by [Hajimari](https://github.com/toboshii/hajimari) | - -| ![](https://user-images.githubusercontent.com/27996771/149444871-38889c9d-862f-41ff-8c05-8ece21da3e9c.png) | -| :--: | -| Git server powered by [Gitea](https://gitea.io/en-us/) | - -| ![](https://user-images.githubusercontent.com/27996771/149445374-58fd0605-bb9a-46e4-81d6-5e584d2b94a9.png) | -| :--: | -| Continuous integration with [Tekton](https://tekton.dev/) | - -| ![](https://user-images.githubusercontent.com/27996771/149444716-fc0d7282-4cf7-4ddb-97a4-1a3fb47ff2b8.png) | -| :--: | -| Continuous deployment with [ArgoCD](https://argoproj.github.io/cd/) | - -| ![](https://user-images.githubusercontent.com/27996771/149446631-1c5d056b-1fdc-48e6-96ba-e1abe1762be0.png) | -| :--: | -| Monitoring dashboard powered by [Grafana](https://grafana.com/) | - -| ![](https://user-images.githubusercontent.com/27996771/149448510-7163310c-2049-4ccd-901d-f11f605bfc32.png) | -| :--: | -| [Matrix](https://matrix.org/) chat server powered by [Element](https://matrix.org/docs/projects/client/element) and [Dendrite](https://matrix.org/docs/projects/server/dendrite) | - -| ![](https://user-images.githubusercontent.com/27996771/149448896-9d79947d-468c-45c6-a81d-b43654e8ab6b.png) | -| :--: | -| Cluster management using [Lens](https://k8slens.dev/) (or you can just use `kubectl`) | - -| ![](https://user-images.githubusercontent.com/27996771/149452309-de4a893b-e94c-4ba8-9119-ea87449cf77e.png) | -| :--: | -| Secret management with [Vault](https://www.vaultproject.io/) | +[screenshot-01]: https://asciinema.org/a/xkBRkwC6e9RAzVuMDXH3nGHp7.svg +[screenshot-02]: https://user-images.githubusercontent.com/27996771/157303477-df2e7410-8f02-4648-a86c-71e6b7e89e35.png +[screenshot-03]: https://user-images.githubusercontent.com/27996771/149445807-0f869eb7-d8f5-4fef-ab97-ac281df91a06.png +[screenshot-04]: https://user-images.githubusercontent.com/27996771/149446631-1c5d056b-1fdc-48e6-96ba-e1abe1762be0.png +[screenshot-05]: https://user-images.githubusercontent.com/27996771/149444871-38889c9d-862f-41ff-8c05-8ece21da3e9c.png +[screenshot-06]: https://user-images.githubusercontent.com/27996771/149448510-7163310c-2049-4ccd-901d-f11f605bfc32.png +[screenshot-07]: https://user-images.githubusercontent.com/27996771/149445374-58fd0605-bb9a-46e4-81d6-5e584d2b94a9.png +[screenshot-08]: https://user-images.githubusercontent.com/27996771/149444716-fc0d7282-4cf7-4ddb-97a4-1a3fb47ff2b8.png +[screenshot-09]: https://user-images.githubusercontent.com/27996771/149448896-9d79947d-468c-45c6-a81d-b43654e8ab6b.png +[screenshot-10]: https://user-images.githubusercontent.com/27996771/149452309-de4a893b-e94c-4ba8-9119-ea87449cf77e.png ### Tech stack - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LogoNameDescription
AnsibleAutomate bare metal provisioning and configuration
ArgoCDGitOps tool built to deploy applications to Kubernetes
cert-managerCloud native certificate management
CloudflareDNS and Tunnel
DockerEphermeral PXE server and convenient tools container
ExternalDNSSynchronizes exposed Kubernetes Services and Ingresses with DNS providers
GiteaSelf-hosted Git service
GrafanaOperational dashboards
HelmThe package manager for Kubernetes
K3sLightweight distribution of Kubernetes
KubernetesContainer-orchestration system, the backbone of this project
LokiLog aggregation system
LonghornCloud native distributed block storage for Kubernetes
MetalLBBare metal load-balancer for Kubernetes
NGINXKubernetes Ingress Controller
PrometheusSystems monitoring and alerting toolkit
RenovateAutomatically update dependencies
Rocky LinuxBase OS for Kubernetes nodes
TektonCloud native solution for building CI/CD systems
TrowPrivate container registry
VaultSecrets and encryption management system
LogoNameDescription
AnsibleAutomate bare metal provisioning and configuration
ArgoCDGitOps tool built to deploy applications to Kubernetes
cert-managerCloud native certificate management
CloudflareDNS and Tunnel
DockerEphermeral PXE server and convenient tools container
ExternalDNSSynchronizes exposed Kubernetes Services and Ingresses with DNS providers
GiteaSelf-hosted Git service
GrafanaOperational dashboards
HelmThe package manager for Kubernetes
K3sLightweight distribution of Kubernetes
KubernetesContainer-orchestration system, the backbone of this project
LokiLog aggregation system
LonghornCloud native distributed block storage for Kubernetes
MetalLBBare metal load-balancer for Kubernetes
NGINXKubernetes Ingress Controller
PrometheusSystems monitoring and alerting toolkit
RenovateAutomatically update dependencies
Rocky LinuxBase OS for Kubernetes nodes
TektonCloud native solution for building CI/CD systems
TrowPrivate container registry
VaultSecrets and encryption management system
## Get Started -- [Try it out locally](https://homelab.khuedoan.com/try-locally.html) without any hardware -- [Deploy on real hardware](https://homelab.khuedoan.com/deployment) for real workload +- [Try it out locally](https://homelab.khuedoan.com/installation/development.md) without any hardware +- [Deploy on real hardware](https://homelab.khuedoan.com/installation/production/prerequisites.md) for production workload ## Roadmap -See [roadmap](https://homelab.khuedoan.com/roadmap.html) and [open issues](https://github.com/khuedoan/homelab/issues) for a list of proposed features and known issues. +See [roadmap](https://homelab.khuedoan.com/reference/roadmap) and [open issues](https://github.com/khuedoan/homelab/issues) for a list of proposed features and known issues. ## Contributing Any contributions you make, either big or small, are greatly appreciated. +Please see [contributing guide](https://homelab.khuedoan.com/reference/contributing) for more information. + ## License -> Copyright (c) 2020, 2021, 2022 Khue Doan +Copyright © 2020 - 2022 Khue Doan -
- -Distributed under the GPLv3 License. - -This project is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. - -This project is distributed in the hope that it will be useful, but **WITHOUT ANY WARRANTY**; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. -See the GNU General Public License for more details. - -You should have received a copy of the GNU General Public License along with this project (`LICENSE.md`). -If not, see . - -
+Distributed under the GPLv3 License. +See [license page](https://homelab.khuedoan.com/reference/license) or `LICENSE.md` file for more information. ## Acknowledgements -- [ArgoCD usage in my coworker's homelab](https://github.com/locmai/humble) +- [ArgoCD usage and monitoring configuration in locmai/humble](https://github.com/locmai/humble) - [README template](https://github.com/othneildrew/Best-README-Template) - [Run the same Cloudflare Tunnel across many `cloudflared` processes](https://developers.cloudflare.com/cloudflare-one/tutorials/many-cfd-one-tunnel) - [MAC address environment variable in GRUB config](https://askubuntu.com/questions/1272400/how-do-i-automate-network-installation-of-many-ubuntu-18-04-systems-with-efi-and) diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index e841dc81..00000000 --- a/docs/Makefile +++ /dev/null @@ -1,10 +0,0 @@ -.POSIX: - -default: book - -mermaid*.js: - mdbook-mermaid install . - -.PHONY: book -book: mermaid*.js - mdbook build . diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 430e8346..00000000 --- a/docs/README.md +++ /dev/null @@ -1,11 +0,0 @@ -# Documents - -Documents can be viewed at . -It's running on my other cluster in the [khuedoan/horus](https://github.com/khuedoan/horus) project -(so if the homelab goes down I can still read the documentation). - -To view locally, install [`mdbook`](https://github.com/rust-lang/mdBook#installation) and run: - -``` -mdbook serve -``` diff --git a/docs/book.toml b/docs/book.toml deleted file mode 100644 index b92d7ab1..00000000 --- a/docs/book.toml +++ /dev/null @@ -1,18 +0,0 @@ -[book] -authors = ["Khue Doan"] -language = "en" -multilingual = false -src = "src" -title = "Khue's Homelab" - -[preprocessor.mermaid] -command = "mdbook-mermaid" - -[output.html] -additional-js = ["mermaid.min.js", "mermaid-init.js"] -git-repository-url = "https://github.com/khuedoan/homelab" -edit-url-template = "https://github.com/khuedoan/homelab/edit/master/docs/{path}" - -# TODO deprecate this after 6 months -[output.html.redirect] -"/try-on-a-vm.html" = "/try-locally.html" diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..537ddb97 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,3 @@ +--8<-- +README.md +--8<-- diff --git a/docs/src/try-locally.md b/docs/installation/development.md similarity index 85% rename from docs/src/try-locally.md rename to docs/installation/development.md index 8cbbbdf9..cf94006e 100644 --- a/docs/src/try-locally.md +++ b/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 new file mode 100644 index 00000000..30bfce1a --- /dev/null +++ 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 + + + + ``` + 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 new file mode 100644 index 00000000..649423b0 --- /dev/null +++ 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 b/docs/installation/production/external-resources.md similarity index 81% rename from external/README.md rename to docs/installation/production/external-resources.md index 2704f450..a7d02ec5 100644 --- a/external/README.md +++ b/docs/installation/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 | + + 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 -### Create Minio keys + -TODO: skip this for now + -### Create AWS API key + -TODO: skip this for now - -## Deploy - -Apply Terraform (you will be prompted to log in to Terraform Cloud and enter API keys from the previous steps): - -```sh -# From the project root -make external -``` + ## 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... + diff --git a/docs/src/deployment/post-installation.md b/docs/installation/production/post-installation.md similarity index 86% rename from docs/src/deployment/post-installation.md rename to docs/installation/production/post-installation.md index 47dcf48e..c8f86c23 100644 --- a/docs/src/deployment/post-installation.md +++ b/docs/installation/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 b/docs/installation/production/prerequisites.md similarity index 54% rename from docs/src/deployment/prerequisites.md rename to docs/installation/production/prerequisites.md index bf3bf857..828c7c5c 100644 --- a/docs/src/deployment/prerequisites.md +++ b/docs/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 -- 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) + The initial controller is the machine used to bootstrap the cluster, we only need it once, you can use your laptop or desktop + +- 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. +!!! example -```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 -``` + 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 diff --git a/docs/reference/architecture.md b/docs/reference/architecture.md new file mode 100644 index 00000000..f72a2245 --- /dev/null +++ b/docs/reference/architecture.md @@ -0,0 +1,177 @@ +# Architecture + +## Components + +``` ++--------------+ +| ./apps | +|--------------| +| ./platform | +|--------------| +------------+ +| ./system |- - - -| ./external | +|--------------| +------------+ +| ./bootstrap | +|--------------| +| ./metal | +|--------------| +| HARDWARE | ++--------------+ +``` + +Main components: + +- `./metal`: bare metal management, install Linux and Kubernetes +- `./bootstrap`: GitOps bootstrap with ArgoCD +- `./system`: critical system components for the cluster (load balancer, storage, ingress, operation tools...) +- `./platform`: essential components for service hosting platform (vault, git...) +- `./apps`: user facing applications +- `./external` (optional): externally managed services + +Support components: + +- `./tools`: tools container, includes all the tools you'll need +- `./docs`: all documentation go here, this will generate a searchable web UI +- `./scripts`: scripts to automate common tasks + +## Provisioning flow + +Everything is automated, after you edit the configuration files, you just need to run a single `make` command and it will: + +- (1) Build the `./metal` layer: + - Create an ephemeral, stateless PXE server + - Install Linux on all servers in parallel + - Build a Kubernetes cluster (based on k3s) +- (2) Build the `./bootstrap` layer: + - Install ArgoCD + - Configure the root app to manage other layers (and also manage itself) + +From now on, ArgoCD will do the rest: + +- (3) Build the `./system` layer (storage, networking, monitoring, etc) +- (4) Build the `./platform` layer (Gitea, Vault, SSO, etc) +- (5) Build the `./apps` layer: (Syncthing, Jellyfin, etc) + +```mermaid +flowchart TD + subgraph metal[./metal] + pxe[PXE Server] -.-> linux[Rocky Linux] --> k3s + end + + subgraph bootstrap[./bootstrap] + argocd[ArgoCD] --> rootapp[Root app] + end + + subgraph system[./system] + metallb[MetalLB] + nginx[NGINX] + longhorn[Longhorn] + cert-manager + external-dns[External DNS] + cloudflared + end + + subgraph external[./external] + letsencrypt[Let's Encrypt] + cloudflare[Cloudflare] + end + + letsencrypt -.-> cert-manager + cloudflare -.-> cert-manager + cloudflare -.-> external-dns + cloudflare -.-> cloudflared + + subgraph platform + gitea[Gitea] + tekton[Tekton] + vault[Vault] + end + + subgraph apps + jellyfin[Jellyfin] + matrix[Matrix] + paperless[Paperless] + seafile[Seafile] + end + + make[Run make] -- 1 --> metal -- 2 --> bootstrap -. 3 .-> system -. 4 .-> platform -. 5 .-> apps +``` + +Below is the pseudo code for the entire process, you don't have to read it right now, but it will be handy for debugging. + +??? detailed "Detailed provisioning flow" + + ``` + Human run make: + build ./metal: + install the OS: + download the installer image and extract it + create a PXE server on the controller using Docker Compose: + DHCP server + TFTP server + HTTP server + create init config for each machine + turn the machines on via WoL + the machines boot: + select network boot automatically + broadcast DHCP request + DHCP server reply: + machine IP + TFTP server (next-server) IP + get boot files from TFTP server + GRUB + GRUB config with URL to init config based on MAC address + kernel + initrd + boot to the kernel + download from HTTP server: + init config from the URL in GRUB config + remaining files required to boot + install the OS based on the init config: + configure the system + remaining files required to install + reboot to the new OS + controller see the machines are ready + build a Kubernetes cluster: + download k3s binary + generate cluster token + copy k3s config files + enable k3s service and form a cluster + create KUBECONFIG file + create MetalLB config: + use the last /27 subnet of the network + apply the config + build ./bootstrap: + install ArgoCD: + apply helm chart + wait for status + install root app: + select values file: + if Gitea unreachable (first install): + get data from GitHub + else: + get data from Gitea + apply helm chart + wait for status + ArgoCD apply the rest: + clone git repo + install components based on directories: + ./bootstrap (it manages itself): + argocd + root + ./system: + storage + loadbalancer + ingress + etc + ./platform (depends on ./system): + git: + migrate the homelab repository from GitHub + ArgoCD switch the source from GitHub to Gitea + ci + vault + etc + ./apps (depends on ./system and ./platform): + homepage + jellyfin + etc + ``` diff --git a/docs/src/changelog.md b/docs/reference/changelog.md similarity index 97% rename from docs/src/changelog.md rename to docs/reference/changelog.md index 95e9e401..71847df1 100644 --- a/docs/src/changelog.md +++ b/docs/reference/changelog.md @@ -24,9 +24,9 @@ - Upgrade to Kubernetes 1.23 - Support external resources: - - Cloudflare DNS and Tunnel - - Backblaze for backup - - Auto inject secrets to required namespaces + - Cloudflare DNS and Tunnel + - Backblaze for backup + - Auto inject secrets to required namespaces - Replace self-signed certificates with Let's Encrypt production (with API token injected from the `external` layer) - Add DNS records automatically using external-dns - Easy Cloudflare Tunnel configuration with annotations diff --git a/docs/reference/contributing.md b/docs/reference/contributing.md new file mode 100644 index 00000000..3e0557a1 --- /dev/null +++ b/docs/reference/contributing.md @@ -0,0 +1,33 @@ +# Contributing + +## How to contribute + +### Bug report + +TODO + +### Merge request + +TODO + +### Documentation + +Documents can be viewed at . +It's running on my other cluster in the [khuedoan/horus](https://github.com/khuedoan/horus) project +(so if the homelab goes down I can still read the documentation). + +To edit and view locally, run: + +``` +make docs +``` + +Then visit [localhost:8000](http://localhost:8000) + +## Contributors + +Here is a list of the contributors who have helped improving my homelab. Big shout-out to them! + +- Loc Mai ([@locmai](https://github.com/locmai)) + +If you feel you're missing from this list, feel free to add yourself in a PR. diff --git a/docs/src/reference/faq.md b/docs/reference/faq.md similarity index 100% rename from docs/src/reference/faq.md rename to docs/reference/faq.md diff --git a/docs/reference/license.md b/docs/reference/license.md new file mode 100644 index 00000000..a57587e6 --- /dev/null +++ b/docs/reference/license.md @@ -0,0 +1,5 @@ +Copyright © 2020 - 2022 Khue Doan + +--8<-- +LICENSE.md +--8<-- diff --git a/docs/reference/roadmap.md b/docs/reference/roadmap.md new file mode 100644 index 00000000..a4443eea --- /dev/null +++ b/docs/reference/roadmap.md @@ -0,0 +1,91 @@ +# Roadmap + +!!! info + + Current status: **ALPHA** + +## Alpha requirements + +Literally anything that works. + +## Beta requirements + +Good enough for tinkering and personal usage, and reasonably secure. + +- [x] Automated bare metal provisioning + - [x] Controller set up (Docker) + - [x] OS installation (PXE boot) +- [x] Automated cluster creation (k3s) +- [x] Automated application deployment (ArgoCD) +- [x] Automated DNS management +- [x] Initialize GitOps repository on Gitea automatically +- [x] Observability + - [x] Monitoring + - [x] Logging + - [ ] Alerting +- [ ] SSO +- [ ] Reasonably secure + - [x] Automated certificate management + - [x] Declarative secret management + - [ ] Replace all default passwords with randomly generated ones + - [x] Expose services to the internet securely with Cloudflare Tunnel +- [x] Only use open-source technologies (except external managed services in `./external`) +- [x] Everything is defined as code +- [ ] Backup solution (3 copies, 2 seperate devices, 1 offsite) +- [ ] Define [SLOs](https://en.wikipedia.org/wiki/Service-level_objective): + - [ ] 70% availability (might break in the weekend due to new experimentation) +- [x] Core applications + - [x] Gitea + - [x] Tekton + - [x] Vault + - [x] Private container registry + - [x] Homepage + +## Stable requirements + +Can be used in "production" (for family or even small scale businesses). + +- [x] A single command to deploy everything +- [x] Fast deployment time (from empty hard drive to running services in under 1 hour) +- [ ] Fully _automatic_, not just _automated_ + - [x] Bare-metal OS rolling upgrade + - [x] Kubernetes version rolling upgrade + - [x] Application version upgrade + - [ ] Encrypted backups + - [ ] Secrets rotation + - [x] Self healing +- [ ] Secure by default + - [ ] SELinux + - [ ] Network policies +- [ ] Static code analysis +- [ ] Chaos testing +- [x] Minimal dependency on external services +- [ ] Complete documentation + - [x] Diagram as code + - [x] Book (this book) + - [ ] Walkthrough tutorial and feature demo (video) +- [x] Configuration script for new users +- [ ] SLOs: + - [ ] 99,9% availability (less than 9 hours of downtime per year) + - [ ] 99,99% data durability +- [ ] Clear upgrade path +- [ ] Additional applications + - [ ] Matrix with bridges + - [ ] VPN server + - [ ] PeerTube + - [x] Seafile + - [x] Blog + - [ ] [Development dashboard](https://github.com/khuedoan/homelab-backstage) + +## Unplanned + +Nice to have + +- [ ] Addition applications + - [ ] Mail server +- [ ] Air-gap install +- [ ] Automated testing +- [ ] Security audit +- [ ] Serverless ([Knative](https://knative.dev)) +- [ ] Cluster API ([last attempt](https://github.com/khuedoan/homelab/pull/2)) +- [ ] Split DNS (requires a better router) diff --git a/docs/runbooks/argocd.md b/docs/runbooks/argocd.md new file mode 100644 index 00000000..5d83e218 --- /dev/null +++ b/docs/runbooks/argocd.md @@ -0,0 +1 @@ +# ArgoCD diff --git a/docs/runbooks/cert-manager.md b/docs/runbooks/cert-manager.md new file mode 100644 index 00000000..eca0c473 --- /dev/null +++ b/docs/runbooks/cert-manager.md @@ -0,0 +1 @@ +# cert-manager diff --git a/docs/runbooks/gitea.md b/docs/runbooks/gitea.md new file mode 100644 index 00000000..574981f6 --- /dev/null +++ b/docs/runbooks/gitea.md @@ -0,0 +1 @@ +# Gitea diff --git a/docs/runbooks/longhorn.md b/docs/runbooks/longhorn.md new file mode 100644 index 00000000..c4ff7c6b --- /dev/null +++ b/docs/runbooks/longhorn.md @@ -0,0 +1 @@ +# Longhorn diff --git a/docs/src/reference/secret-management.md b/docs/runbooks/vault.md similarity index 82% rename from docs/src/reference/secret-management.md rename to docs/runbooks/vault.md index 9a1e4e27..2731555c 100644 --- a/docs/src/reference/secret-management.md +++ b/docs/runbooks/vault.md @@ -1,4 +1,4 @@ -# Secret management +# Vault ## Overview @@ -7,8 +7,10 @@ - Secrets that can be generated are automatically generated and stored in Vault. - Integrate with GitOps using [External Secrets Operator](https://external-secrets.io) -> Despite the name "_External_ Secrets Operator", our Vault is deployed on the same cluster. -> HashiCorp Vault can be replaced with AWS Secret Manager, Google Cloud Secret Manager, Azure Key Vault, etc. +!!! info + + Despite the name _External_ Secrets Operator, our Vault is deployed on the same cluster. + HashiCorp Vault can be replaced with AWS Secret Manager, Google Cloud Secret Manager, Azure Key Vault, etc. ```mermaid flowchart TD diff --git a/docs/src/CNAME b/docs/src/CNAME deleted file mode 100644 index 6fa3208a..00000000 --- a/docs/src/CNAME +++ /dev/null @@ -1 +0,0 @@ -homelab.khuedoan.com diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md deleted file mode 100644 index 61782962..00000000 --- a/docs/src/SUMMARY.md +++ /dev/null @@ -1,35 +0,0 @@ -# Summary - -- [Introduction](introduction.md) -- [Try locally](try-locally.md) -- [Deployment](./deployment/README.md) - - [Provisioning flow](./deployment/provisioning-flow.md) - - [Prerequisites](./deployment/prerequisites.md) - - [Configuration](./deployment/configuration.md) - - [Deploy the homelab](./deployment/deployment.md) - - [DNS setup](./deployment/dns.md) - - [External resources (optional)](./deployment/external-resources.md) - - [Post-installation](./deployment/post-installation.md) -- [Troubleshooting](./troubleshooting.md) -- [Tutorials]() - - [Use both GitHub and Gitea](./tutorials/use-both-github-and-gitea.md) - - [Single node cluster adjustments](./tutorials/single-node-cluster-adjustments.md) - - [Add or remove nodes (scale up or down)](./tutorials/add-or-remove-nodes.md) - - [Run commands on multiple nodes](./tutorials/run-commands-on-multiple-nodes.md) - - [Install new applications]() - - [Expose services to the internet](tutorials/expose-services-to-the-internet.md) -- [Runbooks]() - - [ArgoCD]() - - [Gitea]() - - [Vault]() -- [Reference](./reference/README.md) - - [Architecture](./reference/architecture.md) - - [Secret management](./reference/secret-management.md) - - [FAQ](./reference/faq.md) - - [Contributors](./reference/contributors.md) - ---- - -- [Changelog](./changelog.md) -- [Roadmap](./roadmap.md) -- [License](./license.md) diff --git a/docs/src/deployment/README.md b/docs/src/deployment/README.md deleted file mode 100644 index 184c46a8..00000000 --- a/docs/src/deployment/README.md +++ /dev/null @@ -1,10 +0,0 @@ -# Deployment - -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.md) section. diff --git a/docs/src/deployment/configuration.md b/docs/src/deployment/configuration.md deleted file mode 100644 index 04e28254..00000000 --- a/docs/src/deployment/configuration.md +++ /dev/null @@ -1,59 +0,0 @@ -# Configuration - -## Fork this repository - -Because this repository ([khuedoan/homelab](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. - -## Choose the environment - -| Environment | Branch | Recommended setup | -| ----------- | -------- | ------------------------------------- | -| Production | `master` | Real hardware | -| Development | `dev` | A local [k3d](https://k3d.io) cluster | - -For example, if you're trying out the dev VM, use the development environment: - -```sh -git checkout dev -``` - - - -## Run the configure script - -Open the tools container if you haven't already: - -```sh -make tools -``` - -Run the following script to configure the homelab: - -```sh -make configure -``` - -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, for example: - -> - The IP addresses are the desired ones, 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 - -```yaml -# metal/inventories/prod.yml -{{#include ../../../metal/inventories/prod.yml:3:}} -``` - -At the end it will show what has changed. After examining the diff, commit and push the changes. diff --git a/docs/src/deployment/deployment.md b/docs/src/deployment/deployment.md deleted file mode 100644 index f40ed716..00000000 --- a/docs/src/deployment/deployment.md +++ /dev/null @@ -1,23 +0,0 @@ -# Deploy the homelab - -> 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! Check the status using the following command: - -```sh -watch ./scripts/get-status -``` - -While waiting for all services to become healthy, continue to the next section to update your DNS. diff --git a/docs/src/deployment/external-resources.md b/docs/src/deployment/external-resources.md deleted file mode 100644 index 3fe2e23f..00000000 --- a/docs/src/deployment/external-resources.md +++ /dev/null @@ -1 +0,0 @@ -{{#include ../../../external/README.md}} diff --git a/docs/src/deployment/provisioning-flow.md b/docs/src/deployment/provisioning-flow.md deleted file mode 100644 index 73beeb0d..00000000 --- a/docs/src/deployment/provisioning-flow.md +++ /dev/null @@ -1,144 +0,0 @@ -# Provisioning flow - -## Overview - -Everything is automated, after you edit the configuration files, you just need to run a single `make` command and it will: - -- (1) Build the `./metal` layer: - - Create an ephemeral, stateless PXE server - - Install Linux on all servers in parallel - - Build a Kubernetes cluster (based on k3s) -- (2) Build the `./bootstrap` layer: - - Install ArgoCD - - Configure the root app to manage other layers (and also manage itself) - -From now on, ArgoCD will do the rest: - -- (3) Build the `./system` layer (storage, networking, monitoring, etc) -- (4) Build the `./platform` layer (Gitea, Vault, SSO, etc) -- (5) Build the `./apps` layer: (Syncthing, Jellyfin, etc) - -```mermaid -flowchart TD - subgraph metal[./metal] - pxe[PXE Server] -.-> linux[Rocky Linux] --> k3s - end - - subgraph bootstrap[./bootstrap] - argocd[ArgoCD] --> rootapp[Root app] - end - - subgraph system[./system] - metallb[MetalLB] - nginx[NGINX] - longhorn[Longhorn] - cert-manager - external-dns[External DNS] - cloudflared - end - - subgraph external[./external] - letsencrypt[Let's Encrypt] - cloudflare[Cloudflare] - end - - letsencrypt -.-> cert-manager - cloudflare -.-> cert-manager - cloudflare -.-> external-dns - cloudflare -.-> cloudflared - - subgraph platform - gitea[Gitea] - tekton[Tekton] - vault[Vault] - end - - subgraph apps - jellyfin[Jellyfin] - matrix[Matrix] - paperless[Paperless] - seafile[Seafile] - end - - make[Run make] -- 1 --> metal -- 2 --> bootstrap -. 3 .-> system -. 4 .-> platform -. 5 .-> apps -``` - -## Detailed steps - -Below is the pseudo code for the entire process, you don't have to read it right now, but it will be handy for debugging. - -``` -Human run make: - build ./metal: - install the OS: - download the installer image and extract it - create a PXE server on the controller using Docker Compose: - DHCP server - TFTP server - HTTP server - create init config for each machine - turn the machines on via WoL - the machines boot: - select network boot automatically - broadcast DHCP request - DHCP server reply: - machine IP - TFTP server (next-server) IP - get boot files from TFTP server - GRUB - GRUB config with URL to init config based on MAC address - kernel - initrd - boot to the kernel - download from HTTP server: - init config from the URL in GRUB config - remaining files required to boot - install the OS based on the init config: - configure the system - remaining files required to install - reboot to the new OS - controller see the machines are ready - build a Kubernetes cluster: - download k3s binary - generate cluster token - copy k3s config files - enable k3s service and form a cluster - create KUBECONFIG file - create MetalLB config: - use the last /27 subnet of the network - apply the config - build ./bootstrap: - install ArgoCD: - apply helm chart - wait for status - install root app: - select values file: - if Gitea unreachable (first install): - get data from GitHub - else: - get data from Gitea - apply helm chart - wait for status -ArgoCD apply the rest: - clone git repo - install components based on directories: - ./bootstrap (it manages itself): - argocd - root - ./system: - storage - loadbalancer - ingress - etc - ./platform (depends on ./system): - git: - migrate the homelab repository from GitHub - ArgoCD switch the source from GitHub to Gitea - ci - vault - etc - ./apps (depends on ./system and ./platform): - homepage - jellyfin - etc -``` diff --git a/docs/src/introduction.md b/docs/src/introduction.md deleted file mode 100644 index a415a5d7..00000000 --- a/docs/src/introduction.md +++ /dev/null @@ -1,5 +0,0 @@ -# Introduction - -{{#include ../../README.md:introduction}} - -Continue to the next section to try locally, or skip to the deployment guide to deploy on real hardware. diff --git a/docs/src/license.md b/docs/src/license.md deleted file mode 100644 index d1b71cc6..00000000 --- a/docs/src/license.md +++ /dev/null @@ -1 +0,0 @@ -{{#include ../../LICENSE.md}} diff --git a/docs/src/reference/README.md b/docs/src/reference/README.md deleted file mode 100644 index 8db8e26b..00000000 --- a/docs/src/reference/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Reference - -TODO diff --git a/docs/src/reference/architecture.md b/docs/src/reference/architecture.md deleted file mode 100644 index 5ea9cbef..00000000 --- a/docs/src/reference/architecture.md +++ /dev/null @@ -1,30 +0,0 @@ -# Architecture - -TODO - -## Components - -``` -+--------------+ -| ./apps | -|--------------| -| ./platform | -|--------------| +------------+ -| ./system |- - - -| ./external | -|--------------| +------------+ -| ./bootstrap | -|--------------| -| ./metal | -|--------------| -| HARDWARE | -+--------------+ -``` - -- `./metal`: bare metal management, install Linux and Kubernetes -- `./bootstrap`: GitOps bootstrap with ArgoCD -- `./system`: critical system components for the cluster (load balancer, storage, ingress, operation tools...) -- `./platform`: essential components for service hosting platform (vault, git...) -- `./apps`: user facing applications -- `./external` (optional): externally managed services -- `./tools`: tools container, includes all the tools you'll need -- `./docs`: all documentation go here, this will generate a searchable web UI diff --git a/docs/src/reference/contributors.md b/docs/src/reference/contributors.md deleted file mode 100644 index 75074188..00000000 --- a/docs/src/reference/contributors.md +++ /dev/null @@ -1,7 +0,0 @@ -# Contributors - -Here is a list of the contributors who have helped improving my homelab. Big shout-out to them! - -- Loc Mai ([@locmai](https://github.com/locmai)) - -If you feel you're missing from this list, feel free to add yourself in a PR. diff --git a/docs/src/roadmap.md b/docs/src/roadmap.md deleted file mode 100644 index 89e5052e..00000000 --- a/docs/src/roadmap.md +++ /dev/null @@ -1,86 +0,0 @@ -# Roadmap - -> Current status: **Alpha** - -## Alpha requirements - -Literally anything that works. - -## Beta requirements - -Good enough for tinkering and personal usage, and reasonably secure. - -- [x] Automated bare metal provisioning - - [x] Controller set up (Docker) - - [x] OS installation (PXE boot) -- [x] Automated cluster creation (k3s) -- [x] Automated application deployment (ArgoCD) -- [x] Automated DNS management -- [x] Initialize GitOps repository on Gitea automatically -- [x] Observability - - [x] Monitoring - - [x] Logging - - [ ] Alerting -- [ ] SSO -- [ ] Reasonably secure - - [x] Automated certificate management - - [ ] Declarative secrets management - - [ ] Replace all default passwords with randomly generated ones - - [x] Expose services to the internet securely with Cloudflare Tunnel -- [x] Only use open-source technologies (except external managed services in `./external`) -- [x] Everything is defined as code -- [ ] Backup solution (3 copies, 2 seperate devices, 1 offsite) -- [ ] 70% availability (might break in the weekend due to new experimentation) -- [x] Core applications - - [x] Gitea - - [x] Tekton - - [x] Vault - - [x] Private container registry - - [x] Homepage - -## Stable requirements - -Can be used in "production" (for family or even small scale businesses). - -- [x] A single command to deploy everything -- [x] Fast deployment time (from empty hard drive to running services in under 1 hour) -- [ ] Fully _automatic_, not just _automated_ - - [x] Bare-metal OS rolling upgrade - - [x] Kubernetes version rolling upgrade - - [ ] Application version upgrade - - [ ] Encrypted backups - - [ ] Secrets rotation - - [x] Self healing -- [ ] Secure by default - - [ ] SELinux - - [ ] Network policy -- [ ] Static code analysis -- [ ] Chaos testing -- [ ] Minimal dependency on external services -- [ ] Complete documentation - - [x] Diagram as code - - [x] Book (this book) - - [ ] Walkthrough tutorial and feature demo (video) -- [x] Configuration script for new users -- [ ] 99,9% availability (less than 9 hours of downtime per year) -- [ ] 99,99% data durability -- [ ] Additional applications - - [ ] Matrix with bridges - - [ ] VPN server - - [ ] PeerTube - - [x] Seafile - - [x] Blog - - [ ] [Development dashboard](https://github.com/khuedoan/homelab-backstage) - -## Unplanned - -Nice to have - -- [ ] Addition applications - - [ ] Mail server -- [ ] Air-gap install -- [ ] Automated testing -- [ ] Security audit -- [ ] Serverless (Knative) -- [ ] Cluster API (https://github.com/khuedoan/homelab/pull/2) -- [ ] Split DNS (requires a better router) diff --git a/docs/src/tutorials/run-commands-on-multiple-nodes.md b/docs/src/tutorials/run-commands-on-multiple-nodes.md deleted file mode 100644 index 72e5c659..00000000 --- a/docs/src/tutorials/run-commands-on-multiple-nodes.md +++ /dev/null @@ -1,22 +0,0 @@ -# Run commands on multiple nodes - -Use [ansible-console](https://docs.ansible.com/ansible/latest/cli/ansible-console.html): - -```sh -cd metal -make console -``` - -Then enter the command(s) you want to run, for example: - -``` -root@all (4)[f:5]$ uptime -metal0 | CHANGED | rc=0 >> - 10:52:02 up 2 min, 1 user, load average: 0.17, 0.15, 0.06 -metal1 | CHANGED | rc=0 >> - 10:52:02 up 2 min, 1 user, load average: 0.14, 0.11, 0.04 -metal3 | CHANGED | rc=0 >> - 10:52:02 up 2 min, 1 user, load average: 0.03, 0.02, 0.00 -metal2 | CHANGED | rc=0 >> - 10:52:02 up 2 min, 1 user, load average: 0.06, 0.06, 0.02 -``` diff --git a/docs/src/troubleshooting.md b/docs/troubleshooting.md similarity index 83% rename from docs/src/troubleshooting.md rename to docs/troubleshooting.md index 1f58a99c..3c19b3e7 100644 --- a/docs/src/troubleshooting.md +++ b/docs/troubleshooting.md @@ -8,12 +8,14 @@ To view PXE server (includes DHCP, TFTP and HTTP server) logs: ./scripts/pxe-logs ``` -You can view the logs of one or more containers selectively, for example: +!!! tip -```sh -./scripts/pxe-logs dhcp -./scripts/pxe-logs tftp http -``` + You can view the logs of one or more containers selectively, for example: + + ```sh + ./scripts/pxe-logs dhcp + ./scripts/pxe-logs tftp http + ``` ## Nodes not booting from the network diff --git a/docs/src/tutorials/add-or-remove-nodes.md b/docs/tutorials/add-or-remove-nodes.md similarity index 84% rename from docs/src/tutorials/add-or-remove-nodes.md rename to docs/tutorials/add-or-remove-nodes.md index e2e57097..30b1fae7 100644 --- a/docs/src/tutorials/add-or-remove-nodes.md +++ b/docs/tutorials/add-or-remove-nodes.md @@ -4,11 +4,13 @@ Or how to scale vertically. To replace the same node with a clean OS, remove it ## Add new nodes -> You can add multiple nodes at the same time +!!! tip -Ensure that it meets the requirements in [prerequisites](../deployment/prerequisites.md), then add its details to the inventory **at the end of the group** (masters or workers): + You can add multiple nodes at the same time -```diff +Add its details to the inventory **at the end of the group** (masters or workers): + +```diff title="metal/inventories/prod.yml" diff --git a/metal/inventories/prod.yml b/metal/inventories/prod.yml index 7f6474a..1bb2cbc 100644 --- a/metal/inventories/prod.yml @@ -30,11 +32,13 @@ That's it! ## Remove a node -> It is recommended to remove nodes one at a time +!!! danger + + It is recommended to remove nodes one at a time Remove it from the inventory: -```diff +```diff title="metal/inventories/prod.yml" diff --git a/metal/inventories/prod.yml b/metal/inventories/prod.yml index 7f6474a..d12b50a 100644 --- a/metal/inventories/prod.yml diff --git a/docs/tutorials/create-a-new-user-account.md b/docs/tutorials/create-a-new-user-account.md new file mode 100644 index 00000000..debd50ed --- /dev/null +++ b/docs/tutorials/create-a-new-user-account.md @@ -0,0 +1,15 @@ +# 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. diff --git a/docs/src/tutorials/expose-services-to-the-internet.md b/docs/tutorials/expose-services-to-the-internet.md similarity index 81% rename from docs/src/tutorials/expose-services-to-the-internet.md rename to docs/tutorials/expose-services-to-the-internet.md index 9f53e3a7..78c5a43c 100644 --- a/docs/src/tutorials/expose-services-to-the-internet.md +++ b/docs/tutorials/expose-services-to-the-internet.md @@ -1,6 +1,8 @@ # Expose services to the internet -> This tutorial is for Cloudflare Tunnel users, please skip if you use port-forwarding. +!!! info + + This tutorial is for Cloudflare Tunnel users, please skip if you use port-forwarding. Apply the `./external` layer to create a tunnel if you haven't already, then add the following annotations to your `Ingress` object (replace `example.com` with your domain): diff --git a/docs/src/deployment/dns.md b/docs/tutorials/manual-dns-setup.md similarity index 50% rename from docs/src/deployment/dns.md rename to docs/tutorials/manual-dns-setup.md index b41366d6..8cbe34a0 100644 --- a/docs/src/deployment/dns.md +++ b/docs/tutorials/manual-dns-setup.md @@ -1,19 +1,27 @@ -# DNS setup +# Manual DNS setup + +!!! info + + Skip this step if you already use the included Cloudflare setup Before you can access the home page at , you'll need to update your DNS config. Some options for DNS config (choose one): -- Change the DNS config at your domain registrar (easy to automate) -- Change the DNS config in your router (also works with the [`home.arpa`](https://datatracker.ietf.org/doc/html/rfc8375) domain) +- Change the DNS config at your domain registrar (already included and automated) +- Change the DNS config in your router (also works if you don't own a domain) - Use [nip.io](https://nip.io) (suitable for a test environment) ## At your domain registrar (recommended) -I'm using Cloudflare for DNS, continue to the next section for more information. +The default configuration is for Cloudflare DNS, but you can change the code to use other providers. ## In your router +!!! tip + + If you don't have a domain, you can use the `home.arpa` domain (according to [RFC-8375](https://datatracker.ietf.org/doc/html/rfc8375)). + You can add each subdomain one by one, or use a wildcard `*.example.com` and point it to the IP address of the load balancer. To acquire a list of subdomains and their addresses, use this command: @@ -21,6 +29,6 @@ To acquire a list of subdomains and their addresses, use this command: ./scripts/get-dns-config ``` -## Use nip.io +## Use [nip.io](https://nip.io) Preconfigured in the `dev` branch. diff --git a/docs/tutorials/run-commands-on-multiple-nodes.md b/docs/tutorials/run-commands-on-multiple-nodes.md new file mode 100644 index 00000000..81f51f14 --- /dev/null +++ b/docs/tutorials/run-commands-on-multiple-nodes.md @@ -0,0 +1,25 @@ +# Run commands on multiple nodes + +Use [ansible-console](https://docs.ansible.com/ansible/latest/cli/ansible-console.html): + +```sh +cd metal +make console +``` + +Then enter the command(s) you want to run. + +!!! example + + `root@all (4)[f:5]$ uptime` + + ```console + metal0 | CHANGED | rc=0 >> + 10:52:02 up 2 min, 1 user, load average: 0.17, 0.15, 0.06 + metal1 | CHANGED | rc=0 >> + 10:52:02 up 2 min, 1 user, load average: 0.14, 0.11, 0.04 + metal3 | CHANGED | rc=0 >> + 10:52:02 up 2 min, 1 user, load average: 0.03, 0.02, 0.00 + metal2 | CHANGED | rc=0 >> + 10:52:02 up 2 min, 1 user, load average: 0.06, 0.06, 0.02 + ``` diff --git a/docs/src/tutorials/single-node-cluster-adjustments.md b/docs/tutorials/single-node-cluster-adjustments.md similarity index 80% rename from docs/src/tutorials/single-node-cluster-adjustments.md rename to docs/tutorials/single-node-cluster-adjustments.md index ddbea81c..ee279e73 100644 --- a/docs/src/tutorials/single-node-cluster-adjustments.md +++ b/docs/tutorials/single-node-cluster-adjustments.md @@ -6,9 +6,10 @@ Update the following changes, then commit and push. Set the `defaultClassReplicaCount` to 1: -```yaml -# system/longhorn-system/values.yaml -{{#include ../../../system/longhorn-system/values.yaml}} +```yaml title="system/longhorn-system/values.yaml" hl_lines="6" +--8<-- +system/longhorn-system/values.yaml +--8<-- ``` ## Disable automatic upgrade for OS and k3s diff --git a/docs/src/tutorials/use-both-github-and-gitea.md b/docs/tutorials/use-both-github-and-gitea.md similarity index 100% rename from docs/src/tutorials/use-both-github-and-gitea.md rename to docs/tutorials/use-both-github-and-gitea.md diff --git a/docs/user-guide/onboarding.md b/docs/user-guide/onboarding.md new file mode 100644 index 00000000..ff029962 --- /dev/null +++ b/docs/user-guide/onboarding.md @@ -0,0 +1,28 @@ +# 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) diff --git a/metal/README.md b/metal/README.md deleted file mode 100644 index 05e1b5bf..00000000 --- a/metal/README.md +++ /dev/null @@ -1,7 +0,0 @@ -# Bare-metal - -- Ansible renders the configuration file for each bare metal machine (like IP, hostname...) and the PXE server from [templates](./roles/pxe_server/templates) -- The tools container creates sibling containers to build a PXE server (includes DHCP, TFTP and HTTP server) -- Ansible [wake the machines up](./roles/wake/tasks/main.yml) using Wake on LAN -- The machine start the boot process, the OS get installed (through PXE server) and the machine reboots to the new operating system -- Ansible build a Kubernetes cluster based on k3s diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..8811f4ef --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,68 @@ +# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json + +site_name: Khue's Homelab +copyright: Copyright © 2020 - 2022 Khue Doan + +repo_url: https://github.com/khuedoan/homelab + +theme: + name: material + palette: + primary: black + features: + - navigation.indexes + - navigation.expand + - search.highlight + - search.share + +markdown_extensions: + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg + - attr_list + - admonition + - pymdownx.details + - pymdownx.snippets: + check_paths: true + - def_list + - pymdownx.tasklist: + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + +nav: + - Home: index.md + - Installation: + - installation/development.md + - Production: + - installation/production/prerequisites.md + - installation/production/external-resources.md + - installation/production/configuration.md + - installation/production/deployment.md + - installation/production/post-installation.md + - Tutorials: + - tutorials/manual-dns-setup.md + - tutorials/create-a-new-user-account.md + - tutorials/expose-services-to-the-internet.md + - tutorials/use-both-github-and-gitea.md + - tutorials/add-or-remove-nodes.md + - tutorials/run-commands-on-multiple-nodes.md + - tutorials/single-node-cluster-adjustments.md + - Runbooks: + - runbooks/argocd.md + - runbooks/cert-manager.md + - runbooks/gitea.md + - runbooks/longhorn.md + - runbooks/vault.md + - troubleshooting.md + - User guide: + - user-guide/onboarding.md + - Reference: + - reference/architecture.md + - reference/license.md + - reference/changelog.md + - reference/roadmap.md + - reference/contributing.md + - reference/faq.md diff --git a/scripts/README.md b/scripts/README.md deleted file mode 100644 index 95b330d0..00000000 --- a/scripts/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Scripts - -Quick (and maybe dirty) scripts to automate common tasks. diff --git a/system/cloudflared/values.yaml b/system/cloudflared/values.yaml index 0a786546..ea08b8c9 100644 --- a/system/cloudflared/values.yaml +++ b/system/cloudflared/values.yaml @@ -4,8 +4,6 @@ cloudflared: config: tunnel: homelab ingress: - # It is safe to put a wildcard here - # Please see https://homelab.khuedoan.com/reference/faq.html#is-it-safe-to-use-wildcard-in-cloudflare-tunnel-ingress-config - hostname: '*.khuedoan.com' service: https://ingress-nginx-controller.ingress-nginx originRequest: diff --git a/tools/README.md b/tools/README.md deleted file mode 100644 index 4e963ef3..00000000 --- a/tools/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Tools container - -Includes all necessary command line tools to provision and maintain the homelab.