From 1405fadf1a18bfffa56bba2ce877727c3e1bf2d7 Mon Sep 17 00:00:00 2001 From: Khue Doan Date: Mon, 19 Sep 2022 02:40:07 +0700 Subject: [PATCH] =?UTF-8?q?refactor(docs):=20apply=20the=20Di=C3=A1taxis?= =?UTF-8?q?=20framework?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Squashed commit of the following: commit 257867f196376df55fa0f57edbdf33967b1da04e Author: Khue Doan Date: Sun Sep 18 16:45:42 2022 +0700 refactor(docs): apply the Diátaxis framework --- .yamllint.yaml | 1 + README.md | 1 + docs/{runbooks => concepts}/documentation.md | 3 +- .../pxe-boot.md} | 2 +- .../secrets-management.md | 8 +- .../{runbooks => concepts}/tools-container.md | 2 +- .../install-pre-commit-hooks.md | 4 +- docs/getting-started/user-onboarding.md | 46 +++++++ .../add-or-remove-nodes.md | 0 .../alternate-dns-setup.md} | 2 +- .../disable-dhcp-proxy-in-dnsmasq.md} | 9 +- .../expose-services-to-the-internet.md | 0 .../run-commands-on-multiple-nodes.md | 0 .../single-node-cluster-adjustments.md | 0 .../troubleshooting}/argocd.md | 0 .../troubleshooting}/cert-manager.md | 0 .../troubleshooting}/gitea.md | 0 .../troubleshooting}/longhorn.md | 0 .../troubleshooting/pxe-boot.md} | 2 +- .../troubleshooting}/vault.md | 0 .../use-both-github-and-gitea.md | 0 .../{production => }/post-installation.md | 8 +- docs/installation/production/configuration.md | 2 +- docs/installation/production/deployment.md | 2 +- .../production/external-resources.md | 2 +- docs/installation/production/prerequisites.md | 4 +- docs/installation/sandbox.md | 23 ++-- .../architecture/decision-records.md | 116 ++++++++++++++++++ .../architecture/networking.md | 0 docs/{ => reference}/architecture/overview.md | 0 docs/tutorials/create-a-new-user-account.md | 15 --- docs/user-guide/onboarding.md | 28 ----- mkdocs.yml | 54 ++++---- 33 files changed, 227 insertions(+), 107 deletions(-) rename docs/{runbooks => concepts}/documentation.md (90%) rename docs/{architecture/bare-metal-provisioning.md => concepts/pxe-boot.md} (97%) rename docs/{architecture => concepts}/secrets-management.md (94%) rename docs/{runbooks => concepts}/tools-container.md (98%) rename docs/{tutorials => getting-started}/install-pre-commit-hooks.md (58%) create mode 100644 docs/getting-started/user-onboarding.md rename docs/{tutorials => how-to-guides}/add-or-remove-nodes.md (100%) rename docs/{tutorials/manual-dns-setup.md => how-to-guides/alternate-dns-setup.md} (97%) rename docs/{runbooks/dnsmasq.md => how-to-guides/disable-dhcp-proxy-in-dnsmasq.md} (83%) rename docs/{tutorials => how-to-guides}/expose-services-to-the-internet.md (100%) rename docs/{tutorials => how-to-guides}/run-commands-on-multiple-nodes.md (100%) rename docs/{tutorials => how-to-guides}/single-node-cluster-adjustments.md (100%) rename docs/{runbooks => how-to-guides/troubleshooting}/argocd.md (100%) rename docs/{runbooks => how-to-guides/troubleshooting}/cert-manager.md (100%) rename docs/{runbooks => how-to-guides/troubleshooting}/gitea.md (100%) rename docs/{runbooks => how-to-guides/troubleshooting}/longhorn.md (100%) rename docs/{troubleshooting.md => how-to-guides/troubleshooting/pxe-boot.md} (98%) rename docs/{runbooks => how-to-guides/troubleshooting}/vault.md (100%) rename docs/{tutorials => how-to-guides}/use-both-github-and-gitea.md (100%) rename docs/installation/{production => }/post-installation.md (74%) create mode 100644 docs/reference/architecture/decision-records.md rename docs/{ => reference}/architecture/networking.md (100%) rename docs/{ => reference}/architecture/overview.md (100%) delete mode 100644 docs/tutorials/create-a-new-user-account.md delete mode 100644 docs/user-guide/onboarding.md diff --git a/.yamllint.yaml b/.yamllint.yaml index 18b0c328..699255b5 100644 --- a/.yamllint.yaml +++ b/.yamllint.yaml @@ -1,5 +1,6 @@ ignore: | templates/ + mkdocs.yml extends: default diff --git a/README.md b/README.md index 7cc61b1e..fcab891e 100644 --- a/README.md +++ b/README.md @@ -249,6 +249,7 @@ References: - [Initialize GitOps repository on Gitea and integrate with Tekton by RedHat](https://github.com/redhat-scholars/tekton-tutorial/tree/master/triggers) - [SSO configuration from xUnholy/k8s-gitops](https://github.com/xUnholy/k8s-gitops) - [Pre-commit config from k8s-at-home/flux-cluster-template](https://github.com/k8s-at-home/flux-cluster-template) +- [Diátaxis technical documentation framework](https://diataxis.fr) Here is a list of the contributors who have helped to improve this project. Big shout-out to them! diff --git a/docs/runbooks/documentation.md b/docs/concepts/documentation.md similarity index 90% rename from docs/runbooks/documentation.md rename to docs/concepts/documentation.md index 4fbf3ffb..da5287d0 100644 --- a/docs/runbooks/documentation.md +++ b/docs/concepts/documentation.md @@ -1,6 +1,7 @@ # Documentation (this website) -Documents can be viewed at . +The project uses the [Diátaxis](https://diataxis.fr) technical documentation framework. +It can be viewed at . ## Local development diff --git a/docs/architecture/bare-metal-provisioning.md b/docs/concepts/pxe-boot.md similarity index 97% rename from docs/architecture/bare-metal-provisioning.md rename to docs/concepts/pxe-boot.md index 14104a99..c62a3925 100644 --- a/docs/architecture/bare-metal-provisioning.md +++ b/docs/concepts/pxe-boot.md @@ -1,4 +1,4 @@ -# Bare metal provisioning (PXE boot) +# PXE boot ```mermaid flowchart TD diff --git a/docs/architecture/secrets-management.md b/docs/concepts/secrets-management.md similarity index 94% rename from docs/architecture/secrets-management.md rename to docs/concepts/secrets-management.md index 544aa02a..e7d0e48e 100644 --- a/docs/architecture/secrets-management.md +++ b/docs/concepts/secrets-management.md @@ -1,5 +1,7 @@ # Secrets management +## Overview + - Secrets are stored in [HashiCorp Vault](https://www.vaultproject.io) - Vault is managed with [Vault Operator (Bank Vaults)](https://banzaicloud.com/docs/bank-vaults/operator), automatically initialize and unseal - Secrets that can be generated are automatically generated and stored in Vault. @@ -26,7 +28,7 @@ flowchart TD ClusterSecretStore --> ExternalSecret ``` -## Generate random secret +## Randomly generated secrets This is useful when you want to generate random secrets like admin password and store in Vault. @@ -36,9 +38,9 @@ This is useful when you want to generate random secrets like admin password and --8<-- ``` -## Pulling secrets from Vault to Kubernetes +## How secrets are pulled from Vault to Kubernetes -Commit and push an `ExternalSecret` object, for example: +When you apply an `ExternalSecret` object, for example: ```yaml hl_lines="4 21-23" apiVersion: external-secrets.io/v1beta1 diff --git a/docs/runbooks/tools-container.md b/docs/concepts/tools-container.md similarity index 98% rename from docs/runbooks/tools-container.md rename to docs/concepts/tools-container.md index 11640108..64ac7901 100644 --- a/docs/runbooks/tools-container.md +++ b/docs/concepts/tools-container.md @@ -4,7 +4,7 @@ The tools container makes it easy to get all of the dependencies needed to inter ## How to open it -You can use the default Docker wrapper, or use Nix if you have Nix installed +You can use the default Docker wrapper, or use Nix if you have Nix installed: === "Docker" diff --git a/docs/tutorials/install-pre-commit-hooks.md b/docs/getting-started/install-pre-commit-hooks.md similarity index 58% rename from docs/tutorials/install-pre-commit-hooks.md rename to docs/getting-started/install-pre-commit-hooks.md index 6642b3cd..279b038e 100644 --- a/docs/tutorials/install-pre-commit-hooks.md +++ b/docs/getting-started/install-pre-commit-hooks.md @@ -1,7 +1,5 @@ # Install pre-commit hooks -> TODO: organize developer-focused documentation - Git hook scripts are useful for identifying simple issues before commiting changes. Install [pre-commit](https://pre-commit.com/#install) first, one-liner for Arch users: @@ -15,3 +13,5 @@ Then install git hook scripts: ```sh make git-hooks ``` + +If you want to enable pre-commit on all repositories without enabling it manually, see [automatically enabling pre-commit on repositories](https://pre-commit.com/#automatically-enabling-pre-commit-on-repositories). diff --git a/docs/getting-started/user-onboarding.md b/docs/getting-started/user-onboarding.md new file mode 100644 index 00000000..6502db46 --- /dev/null +++ b/docs/getting-started/user-onboarding.md @@ -0,0 +1,46 @@ +# User onboarding + +=== "For user" + + ## Create user + + Ask an admin to create your account, provide the following information: + + - [ ] Full name (John Doe) + - [ ] Select a username (`johndoe`) + - [ ] Email address (`johndoe@example.com`) + + ## 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) + +=== "For admin" + + ## 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. + +## 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/docs/tutorials/add-or-remove-nodes.md b/docs/how-to-guides/add-or-remove-nodes.md similarity index 100% rename from docs/tutorials/add-or-remove-nodes.md rename to docs/how-to-guides/add-or-remove-nodes.md diff --git a/docs/tutorials/manual-dns-setup.md b/docs/how-to-guides/alternate-dns-setup.md similarity index 97% rename from docs/tutorials/manual-dns-setup.md rename to docs/how-to-guides/alternate-dns-setup.md index 8cbe34a0..752a30af 100644 --- a/docs/tutorials/manual-dns-setup.md +++ b/docs/how-to-guides/alternate-dns-setup.md @@ -1,4 +1,4 @@ -# Manual DNS setup +# Alternate DNS setup !!! info diff --git a/docs/runbooks/dnsmasq.md b/docs/how-to-guides/disable-dhcp-proxy-in-dnsmasq.md similarity index 83% rename from docs/runbooks/dnsmasq.md rename to docs/how-to-guides/disable-dhcp-proxy-in-dnsmasq.md index 5681d651..305243a0 100644 --- a/docs/runbooks/dnsmasq.md +++ b/docs/how-to-guides/disable-dhcp-proxy-in-dnsmasq.md @@ -1,13 +1,14 @@ -# Dnsmasq +# Disable DHCP proxy in dnsmasq ## Overview Dnsmasq is used as either a DHCP server or DHCP proxy server for PXE metal provisioning. Proxy mode is enabled by default allowing the use of existing DHCP servers on the network. -A good description on how DHCP Proxy works can be found on the related [FOG project wiki page](https://wiki.fogproject.org/wiki/index.php?title=ProxyDHCP_with_dnsmasq) +A good description on how DHCP Proxy works can be found on the related [FOG project wiki page](https://wiki.fogproject.org/wiki/index.php?title=ProxyDHCP_with_dnsmasq). -## Disabling Proxy Mode +## Disabling Proxy mode Certain scenarios will require this project to use a DHCP server, such as an air-gap deployment or dedicated VLAN. -To disable proxy mode thereby using dnsmasq as a DHCP server, modify `metal/roles/pxe_server/defaults/main.yml` and set `dhcp_proxy` to `false` + +To disable proxy mode thereby using dnsmasq as a DHCP server, modify `metal/roles/pxe_server/defaults/main.yml` and set `dhcp_proxy` to `false`. diff --git a/docs/tutorials/expose-services-to-the-internet.md b/docs/how-to-guides/expose-services-to-the-internet.md similarity index 100% rename from docs/tutorials/expose-services-to-the-internet.md rename to docs/how-to-guides/expose-services-to-the-internet.md diff --git a/docs/tutorials/run-commands-on-multiple-nodes.md b/docs/how-to-guides/run-commands-on-multiple-nodes.md similarity index 100% rename from docs/tutorials/run-commands-on-multiple-nodes.md rename to docs/how-to-guides/run-commands-on-multiple-nodes.md diff --git a/docs/tutorials/single-node-cluster-adjustments.md b/docs/how-to-guides/single-node-cluster-adjustments.md similarity index 100% rename from docs/tutorials/single-node-cluster-adjustments.md rename to docs/how-to-guides/single-node-cluster-adjustments.md diff --git a/docs/runbooks/argocd.md b/docs/how-to-guides/troubleshooting/argocd.md similarity index 100% rename from docs/runbooks/argocd.md rename to docs/how-to-guides/troubleshooting/argocd.md diff --git a/docs/runbooks/cert-manager.md b/docs/how-to-guides/troubleshooting/cert-manager.md similarity index 100% rename from docs/runbooks/cert-manager.md rename to docs/how-to-guides/troubleshooting/cert-manager.md diff --git a/docs/runbooks/gitea.md b/docs/how-to-guides/troubleshooting/gitea.md similarity index 100% rename from docs/runbooks/gitea.md rename to docs/how-to-guides/troubleshooting/gitea.md diff --git a/docs/runbooks/longhorn.md b/docs/how-to-guides/troubleshooting/longhorn.md similarity index 100% rename from docs/runbooks/longhorn.md rename to docs/how-to-guides/troubleshooting/longhorn.md diff --git a/docs/troubleshooting.md b/docs/how-to-guides/troubleshooting/pxe-boot.md similarity index 98% rename from docs/troubleshooting.md rename to docs/how-to-guides/troubleshooting/pxe-boot.md index d21f38c8..6a855d0f 100644 --- a/docs/troubleshooting.md +++ b/docs/how-to-guides/troubleshooting/pxe-boot.md @@ -1,4 +1,4 @@ -# Troubleshooting +# PXE boot ## PXE server logs diff --git a/docs/runbooks/vault.md b/docs/how-to-guides/troubleshooting/vault.md similarity index 100% rename from docs/runbooks/vault.md rename to docs/how-to-guides/troubleshooting/vault.md diff --git a/docs/tutorials/use-both-github-and-gitea.md b/docs/how-to-guides/use-both-github-and-gitea.md similarity index 100% rename from docs/tutorials/use-both-github-and-gitea.md rename to docs/how-to-guides/use-both-github-and-gitea.md diff --git a/docs/installation/production/post-installation.md b/docs/installation/post-installation.md similarity index 74% rename from docs/installation/production/post-installation.md rename to docs/installation/post-installation.md index 92554bed..2907694d 100644 --- a/docs/installation/production/post-installation.md +++ b/docs/installation/post-installation.md @@ -2,7 +2,7 @@ ## Backup secrets -Save the following files to a safe location (like a password manager): +Save the following files to a safe location like a password manager (if you're using the sandbox, you can skip this step): - `~/.ssh/id_ed25519` - `~/.ssh/id_ed25519.pub` @@ -10,8 +10,6 @@ Save the following files to a safe location (like a password manager): - `~/.terraform.d/credentials.tfrc.json` - `./external/terraform.tfvars` - - ## Admin credentials - ArgoCD: @@ -25,7 +23,3 @@ Save the following files to a safe location (like a password manager): - Gitea: - Username: `gitea_admin` - Password: get from Vault - -## Next steps - -- [User onboarding](../../user-guide/onboarding.md) diff --git a/docs/installation/production/configuration.md b/docs/installation/production/configuration.md index cdb7c89d..5df750f3 100644 --- a/docs/installation/production/configuration.md +++ b/docs/installation/production/configuration.md @@ -1,6 +1,6 @@ # Configuration -Open the [tools container](../../runbooks/tools-container.md), which includes all the tools needed: +Open the [tools container](../../concepts/tools-container.md), which includes all the tools needed: === "Docker" diff --git a/docs/installation/production/deployment.md b/docs/installation/production/deployment.md index 29b71542..1562e3f2 100644 --- a/docs/installation/production/deployment.md +++ b/docs/installation/production/deployment.md @@ -27,4 +27,4 @@ Yes it's that simple! It will take a while to download everything, -you can read the [architecture document](../../architecture/overview.md) while waiting for the deployment to complete. +you can read the [architecture document](../../reference/architecture/overview.md) while waiting for the deployment to complete. diff --git a/docs/installation/production/external-resources.md b/docs/installation/production/external-resources.md index 23cb9848..6704e82a 100644 --- a/docs/installation/production/external-resources.md +++ b/docs/installation/production/external-resources.md @@ -71,7 +71,7 @@ To avoid vendor lock-in, each external provider must have an equivalent alternat - Any other [Terraform backends](https://www.terraform.io/language/settings/backends) - Cloudflare DNS: - Update cert-manager and external-dns to use a different provider - - [Manual DNS setup](../../tutorials/manual-dns-setup.md) + - [Alternate DNS setup](../../how-to-guides/alternate-dns-setup.md) - Cloudflare Tunnel: - Use port forwarding if it's available - Create a small VPS in the cloud and utilize Wireguard and HAProxy to route traffic via it diff --git a/docs/installation/production/prerequisites.md b/docs/installation/production/prerequisites.md index 828c7c5c..3f77abed 100644 --- a/docs/installation/production/prerequisites.md +++ b/docs/installation/production/prerequisites.md @@ -40,7 +40,7 @@ Any modern `x86_64` computer(s) should work, you can use old PCs, laptops or ser | 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](../../how-to-guides/single-node-cluster-adjustments.md) tutorial) | 3 or more for high availability | Additional capabilities: @@ -54,7 +54,7 @@ Additional capabilities: ## Domain -Buying a domain is highly recommended, but if you don't have one, see [manual DNS setup](../../tutorials/manual-dns-setup.md). +Buying a domain is highly recommended, but if you don't have one, see [alternate DNS setup](../../how-to-guides/alternate-dns-setup.md). ## BIOS setup diff --git a/docs/installation/sandbox.md b/docs/installation/sandbox.md index 4518e4b5..f6105e44 100644 --- a/docs/installation/sandbox.md +++ b/docs/installation/sandbox.md @@ -2,17 +2,6 @@ The sandbox is intended for trying out the homelab without any hardware or testing changes before applying them to the production environment. -## Caveats compare to production environment - -The development cluster doesn't have the following features: - -- There is no valid domain name, hence no SSL certificates (some services require valid SSL certificates) -- Only accessible on the host machine -- No backup - - -Please keep in mind that the development cluster may be unstable and things may break (it's for development after all). - ## Prerequisites Host machine: @@ -65,7 +54,7 @@ make The homepage should be available at (ignore the security warning because we don't have valid certificates). -See [admin credentials](../production/post-installation/#admin-credentials) for default passwords. +See [admin credentials](../post-installation/#admin-credentials) for default passwords. ## Clean up @@ -74,3 +63,13 @@ Delete the cluster: ```sh k3d cluster delete homelab-dev ``` + +## Caveats compare to production environment + +The development cluster doesn't have the following features: + +- There is no valid domain name, hence no SSL certificates (some services require valid SSL certificates) +- Only accessible on the host machine +- No backup + +Please keep in mind that the development cluster may be unstable and things may break (it's for development after all). diff --git a/docs/reference/architecture/decision-records.md b/docs/reference/architecture/decision-records.md new file mode 100644 index 00000000..0f364a54 --- /dev/null +++ b/docs/reference/architecture/decision-records.md @@ -0,0 +1,116 @@ +# Decision records + +??? Template + + ## Description of the the change + + **Context** + + CHANGEME + + **Decision** + + CHANGEME + + **Consequences** + + - CHANGEME + +## Refactor the tools container from plain Dockerfile to [Nix](https://nixos.org) + +**Context** + +The previous implementation of the tools container is not reproducible, if someone builds it a few weeks after me, they will receive different versions of the tools. +Also, if you change something in the tool list, everything will be downloaded again, with no caching. + +**Decision** + +Move to Nix shell with a Docker wrapper, in case Nix is not available (see commit `adbaf32`). + +**Consequences** + +- All versions are pinned +- When you change the list of tools, rebuilding is much faster + +## Combine dhcpd and tftpd to dnsmasq in PXE server + +**Context** + +[Original proposal from @Bourne-ID](https://github.com/khuedoan/homelab/issues/70): + +> **Issue statement** +> +> The use of dhcpd is great for air-gap solutions where a new DHCP is required. However for some home networks which does not have the VLAN capability or for users who would like to use common router DHCP services, the use of DHCPD will cause duplicate DHCP servers and will result in potential network disruption, or will limit the ability to auto-provision the Metal stage of this project. +> +> **Proposed Solution: DHCP Proxy** +> +> Use DHCP Proxy services to add PXE features such as Next Server into this project. This allows for users to use the existing DHCP servers which may be locked down or incapable of using Next Server/PXE settings on their network to be able to auto-provision hardware through PXE (with certain common configurations, like static IP allocation or reduction in DHCP request ranges on the DHCP server) +> +> **Proposed Application: DNSMasq** +> +> DNSMasq in Proxy mode interoperates with existing DHCP servers over IPv4 to add features such as next-server, TFTP, etc. where such hardware is either locked or unconfigurable for such services. This would be an opt-in change, configurable through the pxe_server defaults file. +> +> **Proposed Target Audience** +> +> Users who either do not want to create their own VLAN or lack the hardware to configure such services. Users who want to use common router services for DHCP and have router access to configure static IP and/or DHCP allocation ranges. +> +> **Additional Risks with Proposed Change** +> +> - Additional Surface Area for Break-Out Attacks: Originally this project is locked to its own DHCP/VLAN, so any break-outs should be contained accordingly. Using common home networks increases the surface area of break-out attacks if the deployment is compromised. +> - Mitigation: Enrolment into this change is opt in only. +> +> **Proposed Next Steps** +> +> 1. Trial/Adopt/Halt - A discussion with all or a decision by the project maintainers to identify if this change should exist in this project or live on a fork. +> 2. Documentation (This is in flight in any situation). + +**Decision** + +Migrate to dnsmasq (see commit `f650c89`, thanks to [@Bourne-ID](https://github.com/Bourne-ID)) + +**Consequences** + +- DHCP proxy is enabled by default because most people have a standard home network with existing DHCP server, but it can still be disabled to restore the previous behavior + +## Migrate documentation from [mdBook](https://rust-lang.github.io/mdBook) to [MkDocs](https://squidfunk.github.io/mkdocs-material) + +**Context** + +mdBook is very minimal and light weight, which I personally prefer. +However, [Backstage TechDocs](https://backstage.io/docs/features/techdocs/techdocs-overview) which I plan to use currently only supports mkDocs. + +**Decision** + +Migrate documentation from mdBook to MkDocs (see commit `cd41343`). + +**Consequences** + +- We can no longer include only a portion of a file, see [facelessuser/pymdown-extensions#1462](https://github.com/facelessuser/pymdown-extensions/issues/1462). + +## Choosing the base OS + +**Context** + +I've tried several distributions, and each has advantages and disadvantages. +Fedora has a good (enough) balance between stability and new features. + +Alternatives considered: + +- Fedora CoreOS (moved to Rocky in `7667254`): + - Pros: automatic and atomic upgrade, immutable, quick installation + - Cons: hard to run Ansible on (Python is not included) +- CentOS/Rocky Linux (moved to Fedora in `022b816`): + - Pros: relatively stable (however we did encounter a breaking change [#63](https://github.com/khuedoan/homelab/issues/63), still not sure why) + - Cons: kernel and packages are too old +- Debian: couldn't get it to work with PXE boot and Rocky Linux was sufficient so I didn't push any further +- Cluster API (previous attempt in ` a8e4a85`, I hope to get this to work someday): + - Pros: control bare metal machines via Kubernetes API, open the possibility for autoscaling and autohealing + - Cons: doesn't support simple WoL and shutdown via SSH (or similar) + +**Decision** + +Use Fedora as the base OS. + +**Consequences** + +`¯\_(ツ)_/¯` diff --git a/docs/architecture/networking.md b/docs/reference/architecture/networking.md similarity index 100% rename from docs/architecture/networking.md rename to docs/reference/architecture/networking.md diff --git a/docs/architecture/overview.md b/docs/reference/architecture/overview.md similarity index 100% rename from docs/architecture/overview.md rename to docs/reference/architecture/overview.md diff --git a/docs/tutorials/create-a-new-user-account.md b/docs/tutorials/create-a-new-user-account.md deleted file mode 100644 index debd50ed..00000000 --- a/docs/tutorials/create-a-new-user-account.md +++ /dev/null @@ -1,15 +0,0 @@ -# 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/user-guide/onboarding.md b/docs/user-guide/onboarding.md deleted file mode 100644 index ff029962..00000000 --- a/docs/user-guide/onboarding.md +++ /dev/null @@ -1,28 +0,0 @@ -# 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/mkdocs.yml b/mkdocs.yml index c0e7baef..47c837f9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -43,33 +43,35 @@ nav: - installation/production/external-resources.md - installation/production/configuration.md - installation/production/deployment.md - - installation/production/post-installation.md - - Architecture: - - architecture/overview.md - - architecture/bare-metal-provisioning.md - - architecture/secrets-management.md - - architecture/networking.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/dnsmasq.md - - runbooks/documentation.md - - runbooks/gitea.md - - runbooks/longhorn.md - - runbooks/tools-container.md - - runbooks/vault.md - - troubleshooting.md - - User guide: - - user-guide/onboarding.md + - installation/post-installation.md + - Getting started: + - getting-started/user-onboarding.md + - getting-started/install-pre-commit-hooks.md + - Concepts: + - concepts/documentation.md + - concepts/pxe-boot.md + - concepts/secrets-management.md + - concepts/tools-container.md + - How-to guides: + - how-to-guides/alternate-dns-setup.md + - how-to-guides/expose-services-to-the-internet.md + - how-to-guides/use-both-github-and-gitea.md + - how-to-guides/add-or-remove-nodes.md + - how-to-guides/run-commands-on-multiple-nodes.md + - how-to-guides/single-node-cluster-adjustments.md + - how-to-guides/disable-dhcp-proxy-in-dnsmasq.md + - Troubleshooting: + - how-to-guides/troubleshooting/argocd.md + - how-to-guides/troubleshooting/cert-manager.md + - how-to-guides/troubleshooting/gitea.md + - how-to-guides/troubleshooting/longhorn.md + - how-to-guides/troubleshooting/pxe-boot.md + - how-to-guides/troubleshooting/vault.md - Reference: + - Architecture: + - reference/architecture/overview.md + - reference/architecture/networking.md + - reference/architecture/decision-records.md - reference/license.md - reference/changelog.md - reference/roadmap.md