diff --git a/Makefile b/Makefile index 3fb034a4..d4cfe19d 100644 --- a/Makefile +++ b/Makefile @@ -26,22 +26,6 @@ smoke-test: post-install: @./scripts/hacks -tools: - @docker run \ - --rm \ - --interactive \ - --tty \ - --network host \ - --env "KUBECONFIG=${KUBECONFIG}" \ - --volume "/var/run/docker.sock:/var/run/docker.sock" \ - --volume $(shell pwd):$(shell pwd) \ - --volume ${HOME}/.ssh:/root/.ssh \ - --volume ${HOME}/.terraform.d:/root/.terraform.d \ - --volume homelab-tools-cache:/root/.cache \ - --volume homelab-tools-nix:/nix \ - --workdir $(shell pwd) \ - docker.io/nixos/nix nix --experimental-features 'nix-command flakes' develop - # TODO maybe there's a better way to manage backup with GitOps? backup: ./scripts/backup --action setup --namespace=actualbudget --pvc=actualbudget-data diff --git a/README.md b/README.md index 4bc6e429..e8029c0c 100644 --- a/README.md +++ b/README.md @@ -135,7 +135,7 @@ They can't capture all the project's features, but they are sufficient to get a Docker - Ephemeral PXE server and convenient tools container + Ephemeral PXE server @@ -187,6 +187,11 @@ They can't capture all the project's features, but they are sufficient to get a NGINX Kubernetes Ingress Controller + + + Nix + Convenient development shell + ntfy diff --git a/docs/concepts/development-shell.md b/docs/concepts/development-shell.md new file mode 100644 index 00000000..e0287fd1 --- /dev/null +++ b/docs/concepts/development-shell.md @@ -0,0 +1,42 @@ +# Development shell + +The development shell makes it easy to get all of the dependencies needed to interact with the homelab. + +## Prerequisites + +!!! info + + NixOS users can skip this step. + +Install Nix using one of the following methods: + +- [Official Nix installer](https://nixos.org/download) +- [Determinate Nix Installer](https://docs.determinate.systems/getting-started/#installer) + +If you're using the official installer, add the following to your +`~/.config/nix/nix.conf` to enable [Flakes](https://nixos.wiki/wiki/Flakes): + +```conf +experimental-features = nix-command flakes +``` + +## How to open it + +Run the following command: + +```sh +nix develop +``` + +It will open a shell with all the dependencies defined in `./flake.nix`: + +``` +[khuedoan@ryzentower:~/Documents/homelab]$ which kubectl +/nix/store/0558zzzqynzw7rx9dp2i7jymvznd1cqx-kubectl-1.30.1/bin/kubectl +``` + +!!! tip + + If you have [`direnv`](https://direnv.net) installed, you can run `direnv + allow` once and it will automatically enter the Nix shell every time you + `cd` into the project. diff --git a/docs/concepts/tools-container.md b/docs/concepts/tools-container.md deleted file mode 100644 index e7fc6823..00000000 --- a/docs/concepts/tools-container.md +++ /dev/null @@ -1,40 +0,0 @@ -# Tools container - -The tools container makes it easy to get all of the dependencies needed to interact with the homelab. - -## How to open it - -You can use the default Docker wrapper, or use Nix if you have Nix installed: - -=== "Docker" - - ```sh - make tools - ``` - -=== "Nix" - - ```sh - nix develop - ``` - - !!! tip - - If you have [`direnv`](https://direnv.net) installed, you can run `direnv allow` once and it will automatically enter the Nix shell. - -It will open a shell like this: - -``` -[khuedoan@ryzentower:~/Documents/homelab]$ echo hello -hello -``` - -## How it works - -- All dependencies are defined in `./flake.nix` -- When you run `make tools`, it will run a thin Docker wrapper with the `nixos/nix` image (because not everyone has Nix installed) and mount some required volumes -- `nix develop` will start an interactive shell based on the Nix expression in `./flake.nix` and install everything from there - -## Known issues - -- If your Docker engine is not running in rootless mode, all files created by the tools container will be owned by `root` diff --git a/docs/installation/production/configuration.md b/docs/installation/production/configuration.md index 3d9ce6ee..c9296001 100644 --- a/docs/installation/production/configuration.md +++ b/docs/installation/production/configuration.md @@ -1,22 +1,10 @@ # Configuration -Open the [tools container](../../concepts/tools-container.md), which includes all the tools needed: +Open the [development shell](../../concepts/development-shell.md), which includes all the tools needed: -=== "Docker" - - ```sh - make tools - ``` - -=== "Nix" - - ```sh - nix develop - ``` - -!!! note - - It will take a while to build the tools container on the first time +```sh +nix develop +``` Run the following script to configure the homelab: diff --git a/docs/installation/production/deployment.md b/docs/installation/production/deployment.md index 416b3d16..5e8baada 100644 --- a/docs/installation/production/deployment.md +++ b/docs/installation/production/deployment.md @@ -1,18 +1,10 @@ # Deployment -Open the tools container if you haven't already: +Open the development shell if you haven't already: -=== "Docker" - - ```sh - make tools - ``` - -=== "Nix" - - ```sh - nix develop - ``` +```sh +nix develop +``` Build the lab: diff --git a/docs/installation/production/prerequisites.md b/docs/installation/production/prerequisites.md index 13863f99..5603fd12 100644 --- a/docs/installation/production/prerequisites.md +++ b/docs/installation/production/prerequisites.md @@ -25,7 +25,7 @@ By using this project you agree to [the license](../../reference/license.md). 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). +- 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 diff --git a/docs/installation/sandbox.md b/docs/installation/sandbox.md index add92336..800c8e1b 100644 --- a/docs/installation/sandbox.md +++ b/docs/installation/sandbox.md @@ -15,7 +15,7 @@ Host machine: Install the following packages: - `docker` -- `make` +- `nix` (see [development shell](../concepts/development-shell.md) for the installation guide) Clone the repository and checkout the development branch: @@ -26,19 +26,11 @@ git checkout dev ## Build -Open the tools container, which includes all the tools needed: +Open the development shell, which includes all the tools needed: -=== "Docker" - - ```sh - make tools - ``` - -=== "Nix" - - ```sh - nix develop - ``` +```sh +nix develop +``` Build a development cluster and bootstrap it: diff --git a/docs/reference/architecture/decision-records.md b/docs/reference/architecture/decision-records.md index f87e0e44..79a37bbd 100644 --- a/docs/reference/architecture/decision-records.md +++ b/docs/reference/architecture/decision-records.md @@ -19,6 +19,27 @@ They are not permanent, we can change them in the future if better alternatives - CHANGEME +## Remove the Docker wrapper for Nix shell + +**Context** + +The Docker wrapper was originally added because not everyone has Nix installed. +However, it is not a good abstraction. Depending on how Docker (or Podman) was +installed, there may be permission issues, and it is slower than running Nix +directly on the host. + +**Decision** + +Remove the Docker wrapper and run the Nix development shell directly. While not +everyone has Nix installed, not everyone has the same Docker setup either. + +**Consequences** + +- Requires an additional step to install Nix, but this is a one-time setup. +- The `make tools` command has been removed, you now need to run `nix develop` + directly. Although it can be added to the `Makefile`, this requires `make` to + be installed, and not everyone has the same version of `make`. + ## Remove HashiCorp Vault **Context** @@ -63,7 +84,7 @@ Update secret references in `kind: ExternalSecret`: + key: gitea.admin ``` -## Manage package versions in tools container +## Manage package versions in development shell **Context** diff --git a/docs/reference/architecture/overview.md b/docs/reference/architecture/overview.md index e0159d1b..321e7138 100644 --- a/docs/reference/architecture/overview.md +++ b/docs/reference/architecture/overview.md @@ -26,7 +26,6 @@ Main components: 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 diff --git a/mkdocs.yml b/mkdocs.yml index 64cbeaee..018ee88b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -19,8 +19,8 @@ theme: markdown_extensions: - pymdownx.emoji: - emoji_index: !!python/name:materialx.emoji.twemoji - emoji_generator: !!python/name:materialx.emoji.to_svg + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg - attr_list - admonition - pymdownx.details @@ -54,7 +54,7 @@ nav: - concepts/pxe-boot.md - concepts/secrets-management.md - concepts/certificate-management.md - - concepts/tools-container.md + - concepts/development-shell.md - concepts/testing.md - How-to guides: - how-to-guides/alternate-dns-setup.md diff --git a/scripts/take-screenshots b/scripts/take-screenshots index 145af9e6..1729b7c7 100755 --- a/scripts/take-screenshots +++ b/scripts/take-screenshots @@ -5,7 +5,7 @@ # - [ ] self contained # - [ ] login automatically credentials from Kubernetes Secrets (is this really needed?) -# TODO put this in tools container or use Docker +# TODO put this in ../flake.nix or use Docker # pip install selenium # sudo pacman -S geckodriver