manual_slop/docs/guide_docker_deployment.md

# 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
./scripts/docker_build.sh
```

Or use the helper:
```bash
./scripts/docker_build.sh
```

## Pushing to Gitea Registry

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

```bash
./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).

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

## Pulling from Gitea Registry on Unraid

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

```bash
# 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:
```yaml
image: git.cozyair.dev/ed/manual_slop:latest
```

## Updating

```bash
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".