supervisor-ui/README.md

Supervisor UI

A modern, sophisticated web interface for Supervisor process management built with Next.js 16 and Tailwind CSS 4.

Features

✅ Completed Features

• Real-time Updates: Server-Sent Events for live process state changes (no manual refresh!)
• Process Control: Start, stop, restart individual processes or groups
• Batch Operations: Multi-select and control multiple processes at once
• Signal Operations: Send Unix signals (HUP, INT, TERM, KILL, USR1, USR2, etc.)
• Process Stdin: Send input directly to process standard input
• Log Viewer: Real-time stdout/stderr logs with auto-scroll and clear
• Charts & Analytics: Process state distribution, uptime, and group statistics
• Search & Filters: Full-text search with state and group filters
• Keyboard Shortcuts: Full keyboard navigation (j/k, Space, /, r, a, Esc, ?)
• Process Groups: Organize and manage processes by groups
• Configuration Management: View and reload Supervisor configuration
• Modern Dashboard: Clean, responsive interface with connection status
• Type-Safe: Full TypeScript coverage with strict mode
• Docker Ready: Multi-stage Docker build for production deployment

See FEATURES.md for detailed feature documentation with commit history.

Tech Stack

• Framework: Next.js 16 (App Router)
• Styling: Tailwind CSS 4 with OKLCH color system
• State Management: TanStack Query (React Query) + Zustand
• API: XML-RPC client for Supervisor
• Type Safety: TypeScript + Zod schemas
• UI Components: Custom components with lucide-react icons
• Notifications: Sonner toast notifications

Prerequisites

• Node.js 20+ with pnpm 10+
• Supervisor instance running with XML-RPC interface enabled

Configuration

Supervisor Setup

Ensure your supervisord.conf has the inet HTTP server enabled:

[inet_http_server]
port = 127.0.0.1:9001
;username = user
;password = pass

Environment Variables

Create a .env.local file:

# Supervisor connection
SUPERVISOR_HOST=localhost
SUPERVISOR_PORT=9001

# Optional: Basic auth (if configured in supervisord.conf)
# SUPERVISOR_USERNAME=user
# SUPERVISOR_PASSWORD=pass

Development

# Install dependencies
pnpm install

# Run development server
pnpm dev

# Open http://localhost:3000

Production Build

# Build for production
pnpm build

# Start production server
pnpm start

Docker Deployment

Using Pre-built Image from Gitea Registry

The easiest way to deploy is using the pre-built image from the Gitea registry:

# Pull the latest image
docker pull dev.pivoine.art/valknar/supervisor-ui:latest

# Run container with custom Supervisor connection
docker run -d \
  -p 3000:3000 \
  -e SUPERVISOR_HOST=your-supervisor-host \
  -e SUPERVISOR_PORT=9001 \
  -e SUPERVISOR_USERNAME=user \
  -e SUPERVISOR_PASSWORD=pass \
  --name supervisor-ui \
  dev.pivoine.art/valknar/supervisor-ui:latest

Build and Run Locally

# Build Docker image with custom defaults
docker build -t supervisor-ui \
  --build-arg SUPERVISOR_HOST=localhost \
  --build-arg SUPERVISOR_PORT=9001 \
  .

# Run container (environment variables override build args)
docker run -d \
  -p 3000:3000 \
  -e SUPERVISOR_HOST=localhost \
  -e SUPERVISOR_PORT=9001 \
  --name supervisor-ui \
  supervisor-ui

Using Docker Compose

Create a .env file for your configuration:

SUPERVISOR_HOST=localhost
SUPERVISOR_PORT=9001
SUPERVISOR_USERNAME=user
SUPERVISOR_PASSWORD=pass

Then use Docker Compose:

# Start with docker-compose
docker-compose up -d

# View logs
docker-compose logs -f supervisor-ui

# Stop
docker-compose down

To use the pre-built image, edit docker-compose.yml and uncomment the registry image line.

Arty Integration

This project supports Arty for container management:

# Start the service
arty up -d supervisor-ui

# View status
arty ps

# View logs
arty logs supervisor-ui

Container Registry

Docker images are automatically built and pushed to the Gitea registry on every commit to main:

• Registry: dev.pivoine.art
• Image: valknar/supervisor-ui
• Tags:
  • latest - Latest stable build from main branch
  • develop - Latest development build
  • v*.*.* - Semantic version tags
  • main-<sha> - Commit-specific builds

Available Tags

# Pull specific versions
docker pull dev.pivoine.art/valknar/supervisor-ui:latest
docker pull dev.pivoine.art/valknar/supervisor-ui:v1.0.0
docker pull dev.pivoine.art/valknar/supervisor-ui:develop

Project Structure

supervisor-ui/
├── app/                        # Next.js App Router
│   ├── api/supervisor/         # API routes (Supervisor proxy)
│   ├── processes/              # Process management page
│   ├── logs/                   # Logs viewer page
│   ├── config/                 # Configuration page
│   └── page.tsx                # Dashboard home
├── components/
│   ├── layout/                 # Layout components (Navbar)
│   ├── process/                # Process-specific components
│   ├── providers/              # Context providers
│   └── ui/                     # Reusable UI components
├── lib/
│   ├── hooks/                  # React Query hooks
│   ├── supervisor/             # Supervisor client & types
│   └── utils/                  # Utility functions
├── Dockerfile                  # Multi-stage production build
├── docker-compose.yml          # Docker Compose configuration
└── package.json                # Dependencies and scripts

API Routes

All Supervisor operations are proxied through Next.js API routes:

• GET /api/health - Health check endpoint
• GET /api/supervisor/system - System information
• GET /api/supervisor/processes - All processes
• GET /api/supervisor/processes/[name] - Single process info
• POST /api/supervisor/processes/[name]/start - Start process
• POST /api/supervisor/processes/[name]/stop - Stop process
• POST /api/supervisor/processes/[name]/restart - Restart process
• GET /api/supervisor/processes/[name]/logs/stdout - Stdout logs
• GET /api/supervisor/processes/[name]/logs/stderr - Stderr logs

Features Roadmap

Completed (11/11 phases)

• Real-time process monitoring with SSE
• Process control (start/stop/restart)
• System status dashboard
• Log viewer with real-time tailing
• Configuration management UI
• Process group operations
• Batch process actions
• Charts and metrics visualization
• Search and filtering
• Signal operations
• Process stdin
• Keyboard shortcuts
• Server-Sent Events for push updates

Optional Future Enhancements

• Multi-instance support (manage multiple Supervisor instances)
• User authentication and authorization
• Process configuration editor
• Log export/download
• Process dependency visualization
• Webhook notifications
• Mobile app (React Native)
• Audit logging

Development Scripts

# Development
pnpm dev              # Start dev server with hot reload
pnpm dev:turbo        # Start dev server with Turbopack

# Build
pnpm build            # Production build
pnpm start            # Start production server

# Code Quality
pnpm lint             # Run ESLint
pnpm lint:fix         # Fix ESLint issues
pnpm format           # Format with Prettier
pnpm type-check       # TypeScript type checking

License

MIT

Credits

Built with inspiration from modern UI patterns and the excellent pastel-ui project configuration.