# Deploying on Unraid

The reference deployment: an Unraid server ("GPU Node") acting as the GPU compute node, with the
control plane either on the same host or elsewhere.

For the general procedure see [INSTALLATION.md](INSTALLATION.md). This page is only what is
different about Unraid.

## Paths

Unraid's container-local storage does not survive an update. Everything ModelForge must keep goes on
`appdata` or an array share:

| What | Where | Why |
| --- | --- | --- |
| Agent identity | `/mnt/user/appdata/modelforge/agent-state` | A node that loses its identity re-enrols as a different node |
| Verified artifacts | `/mnt/user/appdata/modelforge/artifacts` | Large, and re-acquisition is expensive |
| Quarantine | `/mnt/user/appdata/modelforge/quarantine` | Holds artifacts mid-verification |
| Hugging Face cache | `/mnt/user/appdata/modelforge/hf-cache` | Avoids repeated downloads |
| Backups | an array share, ideally a different disk from the database | A backup on the disk it protects is not a backup |

Set them through `MODELFORGE_AGENT_STATE_VOLUME`, `MODELFORGE_AGENT_ARTIFACT_VOLUME`,
`MODELFORGE_AGENT_QUARANTINE_VOLUME`, `MODELFORGE_AGENT_HF_CACHE_VOLUME` and
`MODELFORGE_BACKUP_VOLUME` — all of them accept an absolute bind path as well as a volume name.

**Do not point the backup destination at the same disk as the PostgreSQL data directory.**

## GPU

The NVIDIA plugin and the NVIDIA container runtime must both be present. The Runtime Worker needs
device access:

```bash
docker compose -f docker-compose.yml -f docker-compose.gpu.yml \
               -f docker-compose.runtime-worker.yml up -d runtime-worker
```

## External GPU workloads

An Unraid box usually runs other things that want VRAM — Ollama, Plex transcoding, Tdarr. ModelForge
**observes** that usage and counts it as external pressure in its admission decisions. It never
reclaims it: it will not stop, pause, throttle or reconfigure a workload it does not own, and it has
no mechanism to do so.

The practical consequence: if Plex starts a transcode, ModelForge may begin refusing placements with
`CAPACITY_CONSTRAINED`. That is the intended behaviour. Size your GPU for the sum of what you run, or
accept that the two compete.

## Networking

The agent is outbound-only, so GPU Node needs to reach the control plane and the control plane needs no
route to GPU Node. If the control plane runs elsewhere behind a private CA, use the private-CA overlay
rather than disabling TLS verification — see [NODE_AGENT.md](NODE_AGENT.md).

## Updates

An Unraid OS update restarts containers. Nothing here depends on container-local state, so a node
comes back with the same identity — provided the state volume is on `appdata` as above.

Set `MODELFORGE_NODE_AGENT_IMAGE=modelforge-node-agent:1.1.1` (or the published digest) before a
release deployment. Compose keeps the optional local `build:` path, but production should run the
immutable released image and verify its OCI revision after recreation.

## Scheduled backups

M15 delivered scheduled backups; enabling them on GPU Node is an operator action, not something the
release does for you. `scripts/modelforge_scheduled_backup.sh` is the entry point. Verify one
execution after enabling, and check the recovery dashboard shows a recent verified backup.