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

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

runner/dev/Dockerfile.debug

@@ -0,0 +1,8 @@
+# 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"]

runner/dev/README.md

@@ -0,0 +1,51 @@
+# 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**: Enables debugger attachment and port exposure.
+
+ ```bash
+ cd .. && git apply ./runner/dev/patches/runner_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/runner_debug.patch && cd runner
+ ```

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",
++ },
++ },
+ },
+ }
+

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",
+ },
+ },
  },
  }