chore(runner): add debugging instructions for AI runner container

This commit enhances the developer documentation with steps for
debugging the AI runner container, including setup for DevContainer
and attaching to running containers.

runner/dev/Dockerfile.debug

@@ -0,0 +1,11 @@
+# A Dockerfile for attaching a debugger to the app using debugpy. For more information, see
+# https://code.visualstudio.com/docs/python/debugging#_command-line-debugging.
+FROM livepeer/ai-runner:base
+
+RUN pip install debugpy
+
+# Expose the debugpy port and start the app as usual.
+CMD ["python", "-m", "debugpy", "--listen", "0.0.0.0:5678", "-m", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+
+# If you want to wait for the debugger to attach before starting the app, use the --wait-for-client option.
+# CMD ["python", "-m", "debugpy", "--listen", "0.0.0.0:5678", "--wait-for-client", "-m", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

runner/dev/README.md

@@ -0,0 +1,57 @@
+# Development Documentation
+
+This guide aims to assist developers working on the AI runner, offering detailed instructions for debugging and setting up the development environment.
+
+## Debugging
+
+### Using the Provided DevContainer
+
+Leverage the [VSCode DevContainer](https://code.visualstudio.com/docs/remote/containers) for an efficient debugging experience with the [AI runner](https://github.com/livepeer/ai-worker/tree/main/runner). This configuration automatically prepares a development environment equipped with all necessary tools and dependencies.
+
+**Quickstart with DevContainer:**
+
+1. **Install** [VSCode](https://code.visualstudio.com/download) and the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
+2. **Clone** the repository and open it in VSCode.
+3. **Navigate** to the `runner` directory.
+4. **Open in Container**: Click "Reopen in Container" when prompted, or manually initiate it by pressing `F1`, typing "Reopen in Container", and pressing `Enter`.
+5. **Initialization**: The initial build may take a few minutes. Subsequent starts are faster.
+6. **Begin Debugging**: The AI runner is now set up for debugging.
+
+For more, see the [VSCode documentation on DevContainers](https://code.visualstudio.com/docs/devcontainers/containers).
+
+### Debugging with External Services
+
+To debug the AI runner when it operates within a container orchestrated by external services, such as [go-livepeer](https://github.com/livepeer/go-livepeer/tree/ai-video), follow these steps to attach to the container:
+
+1. **Directory**: Ensure you're in the `runner` directory.
+2. **Build the AI Runner Image**:
+
+   ```bash
+   docker build -t livepeer/ai-runner:base .
+   ```
+
+3. **Build the Debug Image**:
+
+   ```bash
+   docker build -f ./dev/Dockerfile.debug -t livepeer/ai-runner:latest .
+   ```
+
+4. **Apply the Debug Patch**: Implement the required code modifications to facilitate debugger attachment and expose the necessary ports.
+
+   ```bash
+   cd .. && git apply ./runner/dev/patches/debug.patch && cd runner
+   ```
+
+5. **Attach and Debug**: Follow the [guidance on attaching to a running container](https://code.visualstudio.com/docs/python/debugging#_command-line-debugging) for details.
+
+6. **Revert Changes**: After debugging, undo the debug patch.
+
+   ```bash
+   cd .. && git apply -R ./runner/dev/patches/debug.patch && cd runner
+   ```
+
+7. **Rebuild the Image**: Execute a rebuild of the image, ensuring to exclude the debug changes.
+
+   ```bash
+   docker build -t livepeer/ai-runner:latest .
+   ```

runner/dev/patches/debug.patch

@@ -0,0 +1,25 @@
+diff --git a/worker/docker.go b/worker/docker.go
+index e7dcca1..7ad026a 100644
+--- a/worker/docker.go
++++ b/worker/docker.go
+@@ -148,6 +148,7 @@ func (m *DockerManager) createContainer(ctx context.Context, pipeline string, mo
+ 		},
+ 		ExposedPorts: nat.PortSet{
+ 			containerPort: struct{}{},
++			"5678/tcp":    struct{}{},
+ 		},
+ 		Labels: map[string]string{
+ 			containerCreatorLabel: containerCreator,
+@@ -176,6 +177,12 @@ func (m *DockerManager) createContainer(ctx context.Context, pipeline string, mo
+ 					HostPort: containerHostPort,
+ 				},
+ 			},
++			"5678/tcp": []nat.PortBinding{
++				{
++					HostIP:   "0.0.0.0",
++					HostPort: "5678",
++				},
++			},
+ 		},
+ 	}
+