From ea3bbbc828b485aacb073d738852cd39cc043526 Mon Sep 17 00:00:00 2001
From: Ed_ <edwardgz@gmail.com>
Date: Wed, 3 Jun 2026 08:26:35 -0400
Subject: [PATCH] docs(docker): add Unraid deployment guide

---
 docs/guide_docker_deployment.md | 92 +++++++++++++++++++++++++++++++++
 1 file changed, 92 insertions(+)
 create mode 100644 docs/guide_docker_deployment.md

diff --git a/docs/guide_docker_deployment.md b/docs/guide_docker_deployment.md
new file mode 100644
index 00000000..f2ea8033
--- /dev/null
+++ b/docs/guide_docker_deployment.md
@@ -0,0 +1,92 @@
+# Docker Deployment Guide (Unraid)
+
+[Top](../README.md) | [Architecture](guide_architecture.md) | [Tools & IPC](guide_tools.md)
+
+---
+
+## Overview
+
+This guide covers deploying Manual Slop on Unraid (or any Docker host) using the containerized image. The deployment provides:
+- A web-accessible ImGui GUI (browser-based, no local display required)
+- The Hook API on `:8999` for agent access
+- Persistent volumes for projects and app state
+
+## Prerequisites
+
+- Unraid 6.10+ (or any Docker host with compose support)
+- A project share mounted at `/mnt/user/projects` (or edit `docker-compose.yml` to match your path)
+- API keys for the providers you want to use
+
+## Building the Image
+
+From the repo root:
+```bash
+docker build -t manual_slop:latest .
+```
+
+Or use the helper:
+```bash
+./scripts/docker_build.sh
+```
+
+## Running the Container
+
+Edit `docker-compose.yml` to set your volume paths and provider keys (via `.env` file or environment).
+
+```bash
+# Create a .env file with your API keys
+cat > .env <<EOF
+GEMINI_API_KEY=your-key-here
+ANTHROPIC_API_KEY=your-key-here
+DEEPSEEK_API_KEY=your-key-here
+MINIMAX_API_KEY=your-key-here
+EOF
+
+# Start the container
+docker compose up -d
+```
+
+## Accessing the GUI
+
+Open a browser and navigate to:
+- `http://<your-unraid-ip>:8080` for the web client
+- `http://<your-unraid-ip>:8999/status` for the hook API health check
+
+The web client renders the ImGui panels via WebGL. The Hello ImGui web backend streams frame deltas over WebSocket.
+
+## Agent Access
+
+Agents interact with the running container via the Hook API on `:8999`. Examples:
+
+```bash
+# Check status
+curl http://<your-unraid-ip>:8999/status
+
+# Get MMA state
+curl http://<your-unraid-ip>:8999/api/gui/mma_status
+```
+
+See [guide_tools.md](guide_tools.md) for the full Hook API reference.
+
+## Volumes
+
+- `/projects` — Mounted from `/mnt/user/projects` by default. Your project workspaces live here. The `manual_slop.toml` per project is in this directory.
+- `/config` — Mounted from `/mnt/user/appdata/manual_slop` by default. App state: presets, personas, log directory, workspace profiles.
+
+## Updating
+
+```bash
+git pull
+docker build -t manual_slop:latest .
+docker compose up -d
+```
+
+## Backup
+
+Back up `/config` to preserve presets, personas, and workspace profiles. Back up `/projects/<project>/conductor/` to preserve track history.
+
+## Troubleshooting
+
+- **Port conflicts:** Edit `docker-compose.yml` to change the host port (e.g., `"18080:8080"` to use 18080 on the host).
+- **Permission errors:** Ensure the Unraid share has write permissions for the container's UID.
+- **Hook API not responding:** Check `docker logs manual_slop` for the startup output. The hook server should log "HookServer started on :8999".
\ No newline at end of file