Add Unraid UI project documentation and research

- Complete Unraid WebGUI inventory (~100 pages documented) - Unraid GraphQL API research and documentation - Homarr architecture documentation - Orchis GTK theme design tokens (TypeScript) - Project README with implementation plan Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-06 07:44:52 +02:00
parent ce336311b1
commit e881ec6cb5
5 changed files with 3123 additions and 0 deletions
--- a/docs/unraid-ui-project/README.md
+++ b/docs/unraid-ui-project/README.md
@@ -0,0 +1,148 @@
+# 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](./WEBGUI-COMPLETE-INVENTORY.md) | Complete inventory of ~100 Unraid WebGUI pages |
+| [unraid-api-research.md](./unraid-api-research.md) | Unraid GraphQL API documentation |
+| [homarr-architecture.md](./homarr-architecture.md) | Homarr codebase architecture |
+| [orchis-design-system.ts](./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
+
+```bash
+# 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
+
+```env
+UNRAID_HOST=192.168.10.20
+UNRAID_API_KEY=your-api-key-here
+UNRAID_USE_SSL=false
+```
--- a/docs/unraid-ui-project/WEBGUI-COMPLETE-INVENTORY.md
+++ b/docs/unraid-ui-project/WEBGUI-COMPLETE-INVENTORY.md
--- a/docs/unraid-ui-project/homarr-architecture.md
+++ b/docs/unraid-ui-project/homarr-architecture.md
@@ -0,0 +1,60 @@
+# Homarr Architecture
+
+## Tech Stack
+- Next.js 13+ (App Router), React 18, TypeScript
+- Mantine UI (component library)
+- Zustand (client state), React Query (server state)
+- Prisma ORM (SQLite default / PostgreSQL)
+- Turbo monorepo, pnpm workspaces
+
+## Project Structure
+```
+homarr/
+├── apps/web/src/           # Main Next.js app
+│   ├── app/                # App Router pages
+│   ├── components/         # React components
+│   ├── modules/            # Widgets & integrations
+│   ├── stores/             # Zustand stores
+│   └── styles/             # Themes & global CSS
+├── packages/
+│   ├── api-client/         # API client lib
+│   ├── common/             # Shared types/utils
+│   ├── definitions/        # Widget/integration defs
+│   ├── auth/               # Auth logic
+│   └── ui/                 # Shared UI components
+├── prisma/                 # DB schema & migrations
+└── turbo.json
+```
+
+## Widget System
+Each widget in `apps/web/src/modules/`:
+- `definition.ts` - Metadata + Zod config schema
+- `component.tsx` - React component
+- `settings.tsx` - Config panel
+- `server-actions.ts` - Backend operations
+- Registered in module index, auto-discovered
+
+## Integration System
+External service connectors with:
+- API client abstraction, credential management
+- URL/hostname config, SSL handling
+- Error handling, retry, rate limiting, caching
+
+## Theming
+- CSS variables + Mantine theming + Tailwind
+- Light/dark mode, custom color palettes, accent colors
+- Wallpaper/background, font size, border radius customization
+- Theme persisted in database
+
+## Adding New Pages
+1. Create in `apps/web/src/app/(group)/page-name/page.tsx`
+2. Use Mantine UI components
+3. Add API routes in `src/app/api/`
+4. Create Zustand store or use React Query
+5. Update navigation config
+
+## Key Patterns
+- Server Components by default, `'use client'` for interactive
+- TRPC for type-safe RPC
+- Zod schemas for validation
+- Prisma for DB operations
--- a/docs/unraid-ui-project/orchis-design-system.ts
+++ b/docs/unraid-ui-project/orchis-design-system.ts
--- a/docs/unraid-ui-project/unraid-api-research.md
+++ b/docs/unraid-ui-project/unraid-api-research.md
@@ -0,0 +1,81 @@
+# Unraid API Research (Live from XTRM-Unraid v7.2.3)
+
+## API: unraid-api v4.29.2 (NestJS + Apollo GraphQL)
+
+### Connection
+- HTTP: `http://192.168.10.20/graphql`
+- WebSocket: `ws://192.168.10.20/graphql` (graphql-ws protocol)
+- Unix socket: `/var/run/unraid-api.sock`
+- Auth: `x-api-key` header
+
+### GraphQL Queries
+| Query | Description |
+|-------|-------------|
+| `info` | System info (cpu, memory, os, baseboard, devices, display, versions) |
+| `array` | Array state, capacity, disks, parities, caches, parity check status |
+| `disks` / `disk(id)` | Physical disks with SMART status, temp, serial |
+| `docker` | Containers (id, names, state, status, image, ports, autoStart) + networks |
+| `vms` | VMs (id, name, state) |
+| `shares` | Shares (name, free, used, size, include, exclude, cache, color) |
+| `notifications` | Notifications (title, subject, description, importance, type, timestamp) |
+| `vars` | Server variables (version, name, timezone, network, SMB/NFS settings) |
+| `services` | Running services (name, online, uptime, version) |
+| `flash` | Flash drive (guid, vendor, product) |
+| `registration` | License (type, state, keyFile, expiration) |
+| `network` | Network info (accessUrls) |
+| `server` | Server details (owner, guid, wanip, lanip, localurl, remoteurl) |
+| `connect` | Connect status (dynamicRemoteAccess, settings) |
+| `plugins` | Installed plugins (name, version) |
+| `logFiles` / `logFile(path)` | Log file listing and content |
+| `upsDevices` / `upsConfiguration` | UPS monitoring |
+| `apiKeys` | API key management |
+| `customization` | Theme + activation code |
+| `me` / `owner` | Current user / server owner |
+
+### GraphQL Mutations
+| Mutation | Description |
+|----------|-------------|
+| `array.setState` | Start/stop array |
+| `array.addDiskToArray` / `removeDiskFromArray` | Disk management |
+| `array.mountArrayDisk` / `unmountArrayDisk` | Mount/unmount |
+| `docker.start(id)` / `docker.stop(id)` | Container start/stop |
+| `vm.start/stop/pause/resume/forceStop/reboot/reset(id)` | VM power management |
+| `parityCheck.start/pause/resume/cancel` | Parity check control |
+| `notification.create/delete/archive/unread` | Notification CRUD |
+| `apiKey.create/update/delete` | API key management |
+| `customization.setTheme` | Theme switching |
+| `connectSignIn/SignOut` | Unraid Connect |
+| `setupRemoteAccess` | Remote access config |
+
+### GraphQL Subscriptions (Real-time)
+- `systemMetricsCpu` / `systemMetricsCpuTelemetry` / `systemMetricsMemory`
+- `arraySubscription` / `parityHistorySubscription`
+- `notificationAdded` / `notificationsOverview`
+- `logFile` (live log streaming)
+- `upsUpdates`
+- `ownerSubscription` / `serversSubscription`
+
+### Enums
+- ArrayState: STARTED, STOPPED, NEW_ARRAY, RECON_DISK, DISABLE_DISK, etc.
+- ArrayDiskStatus: DISK_NP, DISK_OK, DISK_INVALID, DISK_WRONG, DISK_DSBL, etc.
+- ArrayDiskType: DATA, PARITY, FLASH, CACHE
+- ContainerState: RUNNING, EXITED
+- VmState: NOSTATE, RUNNING, IDLE, PAUSED, SHUTDOWN, SHUTOFF, CRASHED, PMSUSPENDED
+- DiskFsType: XFS, BTRFS, VFAT, ZFS, EXT4, NTFS
+- DiskInterfaceType: SAS, SATA, USB, PCIE, UNKNOWN
+- ThemeName: azure, black, gray, white
+
+### Legacy PHP/Nchan Endpoints
+- Nchan WebSocket channels: `/sub/var`, `/sub/docker`, `/sub/update1-3`, `/sub/diskload`, etc.
+- PHP includes: DashboardApps.php, Control.php, SmartInfo.php, Syslog.php, etc.
+- State INI files at `/var/local/emhttp/`: var.ini, disks.ini, shares.ini, etc.
+- Legacy control: POST to `/update.htm` for commands
+
+### NOT Available via GraphQL
+- Docker create/delete/restart/logs
+- VM create/delete
+- Share CRUD, User CRUD
+- Detailed SMART attributes
+- Disk format/clear, spin up/down
+- System reboot/shutdown
+- Mover operations