homarr/docs/unraid-ui-project

Unraid Custom UI Project

This project transforms the Homarr fork into a custom Unraid management UI with an Orchis GTK theme.

Project Goals

1. Step 1: Recreate all current Unraid WebGUI pages using Homarr as a base, with data from the Unraid GraphQL API
2. Step 2: Apply a custom theme based on the Orchis GTK theme

Project Resources

Document	Description
WEBGUI-COMPLETE-INVENTORY.md	Complete inventory of ~100 Unraid WebGUI pages
unraid-api-research.md	Unraid GraphQL API documentation
homarr-architecture.md	Homarr codebase architecture
orchis-design-system.ts	Orchis theme design tokens (TypeScript)

Unraid Server Connection

• GraphQL Endpoint: http://192.168.10.20/graphql
• Auth: x-api-key header
• Socket: /var/run/unraid-api.sock

Implementation Plan

Phase 1: Foundation Setup

• Create Unraid GraphQL client integration
• Set up API authentication layer
• Configure environment variables for Unraid connection
• Create base types for Unraid data models

Phase 2: Core Pages (Priority Order)

1. Dashboard - System overview with real-time metrics

   • System info, CPU/RAM usage, array status
   • Docker/VM summaries, network, UPS

2. Array Management (Main)

   • Array devices, pool devices, boot device
   • Parity check, array operations

3. Docker Management

   • Container list, start/stop/restart
   • Container details, logs

4. VM Management

   • VM list, power controls
   • VM details, console access

5. Shares

   • User shares, disk shares
   • Share settings, SMB/NFS security

Phase 3: Orchis Theme Integration

• Copy design tokens to src/styles/
• Create Mantine theme override with Orchis values
• Implement light/dark mode with Orchis palettes
• Replace default components with Orchis-styled versions

Phase 4: Settings & Tools

• Settings pages (identification, disk, network, etc.)
• Tools pages (syslog, diagnostics, system devices)
• User management
• Notifications system

Phase 5: Real-time Features

• GraphQL subscriptions for CPU/memory metrics
• Nchan integration for legacy real-time features
• WebSocket connections for live updates

Key Technical Decisions

Homarr Stack

• Next.js 13 (Pages Router in this version)
• Mantine UI v6
• tRPC for type-safe API
• Zustand for state management
• React Query for server state

Data Sources

Feature	Source
System info, array, shares	Unraid GraphQL API
Docker containers	Unraid GraphQL API
VMs	Unraid GraphQL API
Real-time CPU/RAM	GraphQL Subscriptions
Real-time disk I/O	Nchan WebSocket (/sub/diskload)
Legacy features	PHP endpoints where needed

API Gaps (Require Legacy Endpoints)

• Docker create/delete/restart/logs
• VM create/delete
• Share CRUD, User CRUD
• System reboot/shutdown
• Mover operations

Directory Structure (New Files)

src/
├── lib/
│   └── unraid/
│       ├── client.ts           # GraphQL client
│       ├── types.ts            # TypeScript types
│       └── queries/            # GraphQL queries
├── pages/
│   └── unraid/
│       ├── dashboard.tsx       # Dashboard page
│       ├── array/              # Array pages
│       ├── docker/             # Docker pages
│       ├── vms/                # VM pages
│       ├── shares/             # Share pages
│       ├── settings/           # Settings pages
│       └── tools/              # Tools pages
├── components/
│   └── unraid/
│       ├── Dashboard/          # Dashboard components
│       ├── Array/              # Array components
│       ├── Docker/             # Docker components
│       └── ...
└── styles/
    └── orchis/
        ├── theme.ts            # Mantine theme config
        ├── variables.css       # CSS custom properties
        └── components.css      # Component overrides

Getting Started

# Install dependencies
yarn install

# Set up environment
cp .env.example .env.local
# Edit .env.local with your Unraid API key

# Run development server
yarn dev

Environment Variables

UNRAID_HOST=192.168.10.20
UNRAID_API_KEY=your-api-key-here
UNRAID_USE_SSL=false