129 lines
3.6 KiB
Markdown
129 lines
3.6 KiB
Markdown
# 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". |