From 85856bee470d8dbfd0d81e7074ffdde25828f655 Mon Sep 17 00:00:00 2001
From: Christian Schlotter <christian.schlotter@broadcom.com>
Date: Fri, 30 Aug 2024 12:44:30 +0200
Subject: [PATCH] book: document how to use Lima on macOS for development

---
 docs/book/src/developer/guide.md |  2 ++
 docs/book/src/developer/tilt.md  | 24 +++++++++++++++++++++++-
 2 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/docs/book/src/developer/guide.md b/docs/book/src/developer/guide.md
index da8d6145acda..f32ccec6ff95 100644
--- a/docs/book/src/developer/guide.md
+++ b/docs/book/src/developer/guide.md
@@ -25,6 +25,8 @@ You'll need the [docker daemon][docker] v19.03 or newer available.
 
 [docker]: https://docs.docker.com/install/
 
+On MacOS systems using [Lima](https://github.com/lima-vm/lima) is a viable alternative to Docker Desktop.
+
 ### A Cluster
 
 You'll likely want an existing cluster as your [management cluster][mcluster].
diff --git a/docs/book/src/developer/tilt.md b/docs/book/src/developer/tilt.md
index cd2270a773a1..14cddeb0a263 100644
--- a/docs/book/src/developer/tilt.md
+++ b/docs/book/src/developer/tilt.md
@@ -7,7 +7,7 @@ workflow that offers easy deployments and rapid iterative builds.
 
 ## Prerequisites
 
-1. [Docker](https://docs.docker.com/install/): v19.03 or newer
+1. [Docker](https://docs.docker.com/install/): v19.03 or newer (on MacOS e.g. via [Lima](https://github.com/lima-vm/lima))
 2. [kind](https://kind.sigs.k8s.io): v0.24.0 or newer
 3. [Tilt](https://docs.tilt.dev/install.html): v0.30.8 or newer
 4. [kustomize](https://github.com/kubernetes-sigs/kustomize): provided via `make kustomize`
@@ -507,6 +507,28 @@ syntax highlighting and auto-formatting. To enable it for Tiltfile a file associ
 
 NB: The socket defined by `DOCKER_HOST` is used only for the `hack/tools/internal/tilt-prepare` command, the image build is running the `podman build`/`podman push` commands.
 
+## Using Lima
+
+[Lima] can be used instead of Docker Desktop. Please note that especially with CAPD the rootless template of Lima does not work.
+
+The following command creates a working Lima machine for developing Cluster API with CAPD:
+
+```bash
+limactl start template://docker-rootful --name "docker" --tty=false \
+  --set '.provision += {"mode":"system","script":"#!/bin/bash\nset -eux -o pipefail\ncat << EOF > \"/etc/sysctl.d/99-capi.conf\"\nfs.inotify.max_user_watches = 1048576\nfs.inotify.max_user_instances = 8192\nEOF\nsysctl -p \"/etc/sysctl.d/99-capi.conf\""}' \
+  --set '.mounts[0] = {"location": "~", "writable": true}' \
+  --memory 12 --cpus 10 --disk 64 \
+  --vm-type vz --rosetta=true
+```
+
+After creating the Lima machine we need to set `DOCKER_HOST` to the correct path:
+
+```bash
+export DOCKER_HOST=$(limactl list "docker" --format 'unix://{{.Dir}}/sock/docker.sock')
+```
+
+[Lima]: https://github.com/lima-vm/lima
+
 ## Troubleshooting Tilt
 
 ### Tilt is stuck