manual_slop/docs/guide_docker_deployment.md

Docker Deployment Guide (Unraid)

Top | Architecture | Tools & IPC

---

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:

./scripts/docker_build.sh

Or use the helper:

./scripts/docker_build.sh

Pushing to Gitea Registry

If your Gitea instance has a container registry, push the built image:

./scripts/docker_push.sh

This reads your Gitea credentials from credentials.toml (registry_url, username, token) and pushes to https://git.cozyair.dev/ed/manual_slop:latest.

Running the Container

Edit docker-compose.yml to set your volume paths and provider keys (via .env file or environment).

# 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:

# 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 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.

Pulling from Gitea Registry on Unraid

If you pushed the image to Gitea's container registry, pull it on Unraid:

# Login to Gitea registry
docker login git.cozyair.dev -u ed

# Pull the image
docker pull git.cozyair.dev/ed/manual_slop:latest

# Run the container
docker run -d \
  --name manual_slop \
  -p 8999:8999 \
  -p 8080:8080 \
  -v /mnt/user/projects:/projects \
  -v /mnt/user/appdata/manual_slop:/config \
  git.cozyair.dev/ed/manual_slop:latest

Or use docker-compose.yml after editing the image name:

image: git.cozyair.dev/ed/manual_slop:latest

Updating

git pull
docker build -t manual_slop:latest .
./scripts/docker_push.sh  # if using Gitea registry
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".