Supervisor UI

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

Features

• Real-time Monitoring: Auto-refreshing process status and system information
• Process Control: Start, stop, and restart processes with a single click
• Modern Dashboard: Clean, responsive interface with dark/light mode
• Backend Proxy: Secure API proxy for Supervisor XML-RPC calls
• Docker Ready: Multi-stage Docker build for production deployment
• Type-Safe: Full TypeScript coverage with Zod validation

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

• Real-time process monitoring
• Process control (start/stop/restart)
• System status dashboard
• Dark/light mode theme
• Docker deployment
• Log viewer with real-time tailing
• Configuration management UI
• Process group operations
• Batch process actions
• Charts and metrics visualization
• Search and filtering
• Keyboard shortcuts
• WebSocket support for push updates

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.