supervisor-ui/README.md

# Supervisor UI

A modern, sophisticated web interface for [Supervisor](http://supervisord.org/) 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](./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:

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

### Environment Variables

Create a `.env.local` file:

```bash
# Supervisor connection
SUPERVISOR_HOST=localhost
SUPERVISOR_PORT=9001

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

## Development

```bash
# Install dependencies
pnpm install

# Run development server
pnpm dev

# Open http://localhost:3000
```

## Production Build

```bash
# 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:

```bash
# 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

```bash
# 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:

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

Then use Docker Compose:

```bash
# 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](https://github.com/yourusername/arty) for container management:

```bash
# 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

```bash
# 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)
- [x] Real-time process monitoring with SSE
- [x] Process control (start/stop/restart)
- [x] System status dashboard
- [x] Log viewer with real-time tailing
- [x] Configuration management UI
- [x] Process group operations
- [x] Batch process actions
- [x] Charts and metrics visualization
- [x] Search and filtering
- [x] Signal operations
- [x] Process stdin
- [x] Keyboard shortcuts
- [x] 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

```bash
# 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](https://github.com/yourusername/pastel-ui) project configuration.