Add documentation on setting up live debugging (#1653)

Adds a short doc on how to set up breakpoints with VSCode through Tilt.
Also expands on the existing podman local environment document.

Signed-off-by: Tayler Geiger <[email protected]>

Author: trgeiger

Diff for: dev/local-debugging-with-tilt-and-vscode.md

@@ -0,0 +1,48 @@
+# Local Debugging in VSCode with Tilt
+
+This tutorial will show you how to connect the go debugger in VSCode to your running
+kind cluster with Tilt for live debugging.
+
+* Follow the instructions in [this document](podman/setup-local-env-podman.md) to set up your local kind cluster and image registry.
+* Next, execute `tilt up` to start the Tilt service (if using podman, you might need to run `DOCKER_BUILDKIT=0 tilt up`).
+
+Press space to open the web UI where you can monitor the current status of operator-controller and catalogd inside Tilt.
+
+Create a `launch.json` file in your operator-controller repository if you do not already have one.
+Add the following configurations:
+
+```json
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Debug operator-controller via Tilt",
+            "type": "go",
+            "request": "attach",
+            "mode": "remote",
+            "port": 30000,
+            "host": "localhost",
+            "cwd": "${workspaceFolder}",
+            "trace": "verbose"
+        },
+        {
+            "name": "Debug catalogd via Tilt",
+            "type": "go",
+            "request": "attach",
+            "mode": "remote",
+            "port": 20000,
+            "host": "localhost",
+            "cwd": "${workspaceFolder}",
+            "trace": "verbose"
+        },
+    ]
+}
+```
+
+This creates two "Run and debug" entries in the Debug panel of VSCode.
+
+Now you can start either debug configuration depending on which component you want to debug.
+VSCode will connect the debugger to the port exposed by Tilt.
+
+Breakpoints should now be fully functional. The debugger can even maintain its
+connection through live code updates.

Diff for: dev/podman/setup-local-env-podman.md

@@ -1,54 +1,103 @@
-## The following are Podman specific steps used to set up on a MacBook (Intel or Apple Silicon)
+# Configuring Podman for Tilt
 
-### Verify installed tools (install if needed)
+The following tutorial explains how to set up a local development environment using Podman and Tilt on a Linux host.
+A few notes on achieving the same result for MacOS are included at the end, but you will likely need to do some
+tinkering on your own.
+
+## Verify installed tools (install if needed)
+
+Ensure you have installed [Podman](https://podman.io/), [Kind](https://github.com/kubernetes-sigs/kind/), and [Tilt](https://tilt.dev/).
 
 ```sh
 $ podman --version
 podman version 5.0.1
 $ kind version
-kind v0.23.0 go1.22.3 darwin/arm64
-
-(optional)
+kind v0.26.0 go1.23.4 linux/amd64
 $ tilt version
-v0.33.12, built 2024-03-28
+v0.33.15, built 2024-05-31
 ```
 
-### Start Kind with a local registry
-Use this [helper script](./kind-with-registry-podman.sh) to create a local single-node Kind cluster with an attached local image registry.
+## Start Kind with a local registry
 
-#### Disable secure access on the local kind registry:
+Use this [helper script](./kind-with-registry-podman.sh) to create a local single-node Kind cluster with an attached local image registry.
 
-`podman inspect kind-registry --format '{{.NetworkSettings.Ports}}'`
 
-With the port you find for 127.0.0.1 edit the Podman machine's config file:
+## Disable secure access on the local kind registry:
 
-`podman machine ssh`
+Verify the port used by the image registry:
 
-`sudo vi /etc/containers/registries.conf.d/100-kind.conf`
+```sh
+podman inspect kind-registry --format '{{.NetworkSettings.Ports}}'
+```
 
-Should look like:
+Edit `/etc/containers/registries.conf.d/100-kind.conf` so it contains the following, substituting 5001 if your registry is using a different port:
 
 ```ini
 [[registry]]
 location = "localhost:5001"
 insecure = true
 ```
 
-### export DOCKER_HOST
+## Configure the Podman socket
 
-`export DOCKER_HOST=unix:///var/run/docker.sock`
+Tilt needs to connect to the Podman socket to initiate image builds. The socket address can differ
+depending on your host OS and whether you want to use rootful or rootless Podman. If you're not sure,
+you should use rootless.
 
+You can start the rootless Podman socket by running `podman --user start podman.socket`.
+If you would like to automatically start the socket in your user session, you can run
+`systemctl --user enable --now podman.socket`.
 
-### Optional - Start tilt with the tilt file in the parent directory
+Find the location of your user socket with `systemctl --user status podman.socket`:
 
-`DOCKER_BUILDKIT=0 tilt up`
+```sh
+● podman.socket - Podman API Socket
+     Loaded: loaded (/usr/lib/systemd/user/podman.socket; enabled; preset: disabled)
+     Active: active (listening) since Tue 2025-01-28 11:40:50 CST; 7s ago
+ Invocation: d9604e587f2a4581bc79cbe4efe9c7e7
+   Triggers: ● podman.service
+       Docs: man:podman-system-service(1)
+     Listen: /run/user/1000/podman/podman.sock (Stream)
+     CGroup: /user.slice/user-1000.slice/[email protected]/app.slice/podman.socket
+```
 
-### Optional troubleshooting
+The location of the socket is shown in the `Listen` section, which in the example above
+is `/run/user/1000/podman/podman.sock`.
 
-In some cases it may be needed to do
+Set `DOCKER_HOST` to a unix address at the socket location:
+
+```sh
+export DOCKER_HOST=unix:///run/user/1000/podman/podman.sock
 ```
-sudo podman-mac-helper install
+
+Some systems might symlink the Podman socket to a docker socket, in which case
+you might need to try something like:
+
+```sh
+export DOCKER_HOST=unix:///var/run/docker.sock
 ```
+
+## Start Tilt
+
+Running Tilt with a container engine other than Docker requires setting `DOCKER_BUILDKIT=0`.
+You can export this, or just run:
+
+```sh
+DOCKER_BUILDKIT=0 tilt up
 ```
+
+## MacOS Troubleshooting
+
+The instructions above are written for use on a Linux system. You should be able to create
+the same or a similar configuration on MacOS, but specific steps will differ.
+
+In some cases you might need to run: 
+
+```sh
+sudo podman-mac-helper install
+
 podman machine stop/start
 ```
+
+When disabling secure access to the registry, you will need to first enter the Podman virtual machine:
+`podman machine ssh`