refactor!: remove the Docker wrapper for Nix shell

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

README.md

@@ -135,7 +135,7 @@ They can't capture all the project's features, but they are sufficient to get a
     <tr>
         <td><img width="32" src="https://www.docker.com/wp-content/uploads/2022/03/Moby-logo.png"></td>
         <td><a href="https://www.docker.com">Docker</a></td>
-        <td>Ephemeral PXE server and convenient tools container</td>
+        <td>Ephemeral PXE server</td>
     </tr>
     <tr>
         <td><img width="32" src="https://github.com/kubernetes-sigs/external-dns/raw/master/docs/img/external-dns.png"></td>
@@ -187,6 +187,11 @@ They can't capture all the project's features, but they are sufficient to get a
         <td><a href="https://www.nginx.com">NGINX</a></td>
         <td>Kubernetes Ingress Controller</td>
     </tr>
+    <tr>
+        <td><img width="32" src="https://raw.githubusercontent.com/NixOS/nixos-artwork/refs/heads/master/logo/nix-snowflake-colours.svg"></td>
+        <td><a href="https://nixos.org">Nix</a></td>
+        <td>Convenient development shell</td>
+    </tr>
     <tr>
         <td><img width="32" src="https://ntfy.sh/_next/static/media/logo.077f6a13.svg"></td>
         <td><a href="https://ntfy.sh">ntfy</a></td>

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.

docs/concepts/tools-container.md

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

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
-
+nix develop
-    ```sh
+```
-    make tools
-    ```
-
-=== "Nix"
-
-    ```sh
-    nix develop
-    ```
-
-!!! note
-
-     It will take a while to build the tools container on the first time
 
 Run the following script to configure the homelab:
 

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
-
+nix develop
-    ```sh
+```
-    make tools
-    ```
-
-=== "Nix"
-
-    ```sh
-    nix develop
-    ```
 
 Build the lab:
 

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
 

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
-
+nix develop
-    ```sh
+```
-    make tools
-    ```
-
-=== "Nix"
-
-    ```sh
-    nix develop
-    ```
 
 Build a development cluster and bootstrap it:
 

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

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
 

mkdocs.yml

@@ -19,8 +19,8 @@ theme:
 
 markdown_extensions:
   - pymdownx.emoji:
-      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
-      emoji_generator: !!python/name:materialx.emoji.to_svg
+      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

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