docker-management

Docker Management on Unraid

Unraid has two Docker management layers:

1. Standard Docker CLI -- full Docker engine with socket at /var/run/docker.sock
2. Unraid XML template system -- proprietary configuration format integrated with the WebGUI

Docker CLI

The standard Docker CLI works directly on Unraid. All docker and docker compose commands are available over SSH.

docker ps -a
docker logs container_name
docker exec -it container_name /bin/bash
docker stats --no-stream

The Docker socket is at /var/run/docker.sock for API access.

XML Template System

Unraid stores container configuration as XML templates, not as Compose files or docker run commands. The WebGUI reads and writes these templates.

Template Location

/boot/config/plugins/dockerMan/templates-user/

Each container has one XML file (e.g., my-plex.xml). These persist across reboots on the USB flash drive.

Template Format

<Container version="2">
  <Name>plex</Name>
  <Repository>plexinc/pms-docker:latest</Repository>
  <Registry>https://hub.docker.com/r/plexinc/pms-docker</Registry>
  <Network>bridge</Network>
  <Privileged>false</Privileged>
  <WebUI>http://[IP]:[PORT:32400]/web</WebUI>

  <!-- Port mapping: Target=container, Default=host, Mode=tcp|udp -->
  <Config Name="Web Port" Target="32400" Default="32400"
    Type="Port" Mode="tcp" Display="always" Required="true"/>

  <!-- Volume mapping: Target=container path, Default=host path -->
  <Config Name="AppData" Target="/config" Default="/mnt/user/appdata/plex"
    Type="Path" Mode="rw" Display="always" Required="true"/>
  <Config Name="Media" Target="/media" Default="/mnt/user/media"
    Type="Path" Mode="ro" Display="always" Required="false"/>

  <!-- Environment variable -->
  <Config Name="PLEX_CLAIM" Target="PLEX_CLAIM" Default=""
    Type="Variable" Display="always" Required="false"/>

  <!-- Template metadata (for Community Applications) -->
  <Icon>https://raw.githubusercontent.com/.../plex-icon.png</Icon>
  <Overview>Plex Media Server organizes your media libraries.</Overview>
  <Category>MediaServer:Video</Category>
  <Support>https://forums.plex.tv/</Support>
  <ExtraParams>--runtime=nvidia</ExtraParams>
  <PostArgs/>
</Container>

Config Element Attributes

Attribute	Values	Purpose
Type	Port, Path, Variable, Device	Config entry type
Mode	tcp, udp, rw, ro	Port protocol or path access mode
Display	always, advanced, always-hide	Visibility in WebGUI
Required	true, false	Whether user must provide a value
Target	string	Container-side port/path/env name
Default	string	Default host-side value
Mask	true, false	Hide value in UI (for secrets)

Template-to-Docker-Run Conversion

Unraid uses PHP helper scripts to convert XML templates into docker run commands internally. The conversion maps:

• <Repository> to image name
• <Config Type="Port"> to -p host:container/protocol
• <Config Type="Path"> to -v host:container:mode
• <Config Type="Variable"> to -e NAME=VALUE
• <Config Type="Device"> to --device host:container
• <Network> to --network
• <ExtraParams> appended verbatim
• <Privileged>true</Privileged> to --privileged

Create a Template Programmatically

Write an XML file to the templates directory and restart the Docker service or trigger a WebGUI refresh:

cat > /boot/config/plugins/dockerMan/templates-user/my-myapp.xml << 'EOF'
<Container version="2">
  <Name>myapp</Name>
  <Repository>author/myapp:latest</Repository>
  <Network>bridge</Network>
  <Config Name="Web Port" Target="8080" Default="8080"
    Type="Port" Mode="tcp" Display="always" Required="true"/>
  <Config Name="AppData" Target="/config" Default="/mnt/user/appdata/myapp"
    Type="Path" Mode="rw" Display="always" Required="true"/>
</Container>
EOF

Appdata Convention

All container persistent data goes under /mnt/user/appdata/<container_name>/:

/mnt/user/appdata/plex/
/mnt/user/appdata/nextcloud/
/mnt/user/appdata/homeassistant/

This convention enables consistent backup strategies and share-level cache settings.

Docker Compose

Docker Compose Manager Plugin

Install from Community Applications. Projects are stored at:

/boot/config/plugins/compose.manager/projects/<project_name>/

Each project directory contains a docker-compose.yml file.

Compose Limitations on Unraid

• Compose-managed containers appear in the Unraid Docker tab but show persistent "update ready" badges
• Compose containers do not fully integrate with Unraid's native Docker UI template system
• Use Compose when template XML is insufficient (multi-container stacks, complex networking)

Place docker-compose.yml files in project subdirectories under the compose manager path.

GraphQL Docker Operations

The Unraid GraphQL API provides container management without SSH:

# List containers
{ docker { containers { id names state status image } } }

# Container logs (with cursor pagination)
{ docker { logs(id: "container:ID", tail: 100) { lines cursor } } }

# Container stats
{ docker { stats(id: "container:ID") { cpuPercent memUsage memLimit } } }

# Network listing
{ docker { networks { name driver } } }

Mutations for lifecycle control:

mutation { docker { start(id: "container:ID") } }
mutation { docker { stop(id: "container:ID") } }
mutation { docker { restart(id: "container:ID") } }

Key Docker Paths

Path	Purpose
/boot/config/docker.cfg	Docker daemon settings
/boot/config/plugins/dockerMan/templates-user/	User container templates
/var/run/docker.sock	Docker API socket
/mnt/user/appdata/	Container persistent data root
/mnt/user/system/docker/docker.img	Docker storage image