minio-webui/MinIO-WebUI-PRD.md

Product Requirements Document (PRD)

MinIO WebUI Management Portal

Version: 1.0
Date: January 22, 2025
Status: Draft
Target Audience: Non-Linux administrators

---

1. Executive Summary

1.1 Purpose

This document outlines the requirements for a web-based user interface that simplifies MinIO administration tasks for non-technical users. The WebUI will provide an intuitive interface for common MinIO operations currently performed via command-line tools.

1.2 Business Objectives

• Reduce the technical barrier for MinIO administration
• Streamline bucket and user management processes
• Provide real-time storage monitoring for billing purposes
• Ensure secure access with IP-based restrictions
• Minimize training requirements for non-Linux administrators

1.3 Key Features

• Bucket creation and management
• User and policy administration
• Storage size monitoring and reporting
• Alias management for MinIO connections
• Secure authentication with encrypted credentials
• IP-based access control

---

2. Product Overview

2.1 Problem Statement

Currently, MinIO administration requires Linux command-line expertise and knowledge of shell scripting. Non-technical staff cannot easily:

• Create new buckets and users
• Monitor storage usage for billing
• Manage access policies
• Check system status

2.2 Solution Overview

A web-based interface that abstracts complex MinIO CLI commands into simple, form-based operations with visual feedback and comprehensive error handling.

2.3 Success Metrics

• 90% reduction in support tickets for MinIO operations
• Sub-5-minute task completion for common operations
• Zero security incidents related to the WebUI
• Weekly automated storage reports generation

---

3. Functional Requirements

3.1 Core Features

3.1.1 Bucket Management

Priority: High

Capabilities:

• Create new buckets with validation
• List all existing buckets
• Display bucket metadata (creation date, size, object count)
• Delete empty buckets
• View bucket policies
• Monitor bucket storage size in real-time

Acceptance Criteria:

• Bucket names follow S3 naming conventions
• Real-time validation prevents invalid names
• Confirmation dialogs for destructive operations
• Storage size displayed in human-readable format (GB, TB)

3.1.2 User Management

Priority: High

Capabilities:

• Create new users with secure password generation
• List all MinIO users
• Associate users with buckets
• Manage user credentials
• Enable/disable user accounts

Acceptance Criteria:

• Password strength requirements enforced
• User creation follows the pattern from kopia-user-create.sh
• Automatic policy generation for bucket access
• Credential display with copy-to-clipboard functionality

3.1.3 Policy Management

Priority: High

Capabilities:

• Create custom IAM-compatible policies
• Apply built-in policies (readonly, readwrite, writeonly)
• Attach policies to users
• View existing policies
• Policy templates for common scenarios

Acceptance Criteria:

• JSON policy validation
• Visual policy builder for non-technical users
• Policy preview before application
• Rollback capability for policy changes

3.1.4 Alias Management

Priority: Medium

Capabilities:

• Add new MinIO server aliases
• Test connection to MinIO servers
• Switch between different MinIO deployments
• Secure credential storage for aliases

Acceptance Criteria:

• Connection testing with meaningful error messages
• Encrypted storage of alias credentials
• Default alias configuration

3.1.5 Storage Monitoring

Priority: High

Capabilities:

• Real-time bucket size monitoring
• Historical storage usage graphs
• Weekly storage reports (automated)
• Export data for billing purposes
• Last modified timestamp for buckets

Acceptance Criteria:

• Matches functionality of speicherauswertung_mail.sh
• Configurable report scheduling
• CSV/PDF export options
• Email notification support

3.2 Authentication & Security

3.2.1 Authentication System

Priority: Critical

Requirements:

• Single admin password stored in .env file
• Password encryption using industry-standard algorithms
• Session management with configurable timeout
• Secure session tokens

Implementation:

• bcrypt for password hashing
• JWT tokens for session management
• 30-minute default session timeout
• Secure cookie settings (HttpOnly, Secure, SameSite)

3.2.2 IP-Based Access Control

Priority: Critical

Requirements:

• Configurable IP whitelist in .env file
• Support for CIDR notation
• Logging of access attempts
• Graceful handling of unauthorized access

Implementation:

ALLOWED_IPS=192.168.1.0/24,10.0.0.5,172.16.0.0/16

3.3 Non-Functional Requirements

3.3.1 Performance

• Page load time < 2 seconds
• API response time < 500ms for read operations
• Support 10 concurrent users
• Handle buckets with up to 1 million objects

3.3.2 Usability

• Mobile-responsive design
• Intuitive navigation without documentation
• Contextual help tooltips
• Progress indicators for long operations
• Clear error messages with resolution steps

3.3.3 Reliability

• 99.9% uptime (excluding planned maintenance)
• Graceful error handling
• Automatic reconnection to MinIO
• Transaction rollback on failures

3.3.4 Security

• HTTPS-only communication
• CSRF protection
• XSS prevention
• SQL injection prevention (if applicable)
• Regular security header implementation
• Audit logging for all operations

---

4. Technical Architecture

4.1 Technology Stack

Backend

• Runtime: Node.js 20 LTS
• Framework: Express.js or Fastify
• Process Manager: PM2 for production
• MinIO Integration: Child process execution of mc CLI
• Authentication: Passport.js with local strategy
• Session Store: Redis or in-memory (configurable)
• Task Scheduler: node-cron for reports

Frontend

• Framework: React 18 with TypeScript
• UI Library: Material-UI (MUI) v5
• State Management: Zustand or Redux Toolkit
• API Client: Axios with interceptors
• Charts: Chart.js for storage graphs
• Forms: React Hook Form with Yup validation

Infrastructure

• Web Server: Nginx reverse proxy
• SSL: Let's Encrypt with auto-renewal
• Monitoring: Prometheus + Grafana (optional)
• Logging: Winston with daily rotation

4.2 System Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│                 │     │                  │     │                 │
│  Web Browser    │────▶│  Nginx Proxy     │────▶│  Node.js App    │
│  (React SPA)    │     │  (SSL, IP Filter)│     │  (Express API)  │
│                 │     │                  │     │                 │
└─────────────────┘     └──────────────────┘     └────────┬────────┘
                                                           │
                                                           ▼
                                                  ┌─────────────────┐
                                                  │                 │
                                                  │  MinIO CLI (mc) │
                                                  │  Child Process  │
                                                  │                 │
                                                  └────────┬────────┘
                                                           │
                                                           ▼
                                                  ┌─────────────────┐
                                                  │                 │
                                                  │  MinIO Server   │
                                                  │  (S3 API)       │
                                                  │                 │
                                                  └─────────────────┘

4.3 API Design

RESTful Endpoints

Authentication:
POST   /api/auth/login
POST   /api/auth/logout
GET    /api/auth/status

Buckets:
GET    /api/buckets
POST   /api/buckets
DELETE /api/buckets/:name
GET    /api/buckets/:name/size
GET    /api/buckets/:name/policy

Users:
GET    /api/users
POST   /api/users
DELETE /api/users/:username
PUT    /api/users/:username/status

Policies:
GET    /api/policies
POST   /api/policies
DELETE /api/policies/:name
POST   /api/policies/:name/attach

Aliases:
GET    /api/aliases
POST   /api/aliases
DELETE /api/aliases/:name
POST   /api/aliases/:name/test

Reports:
GET    /api/reports/storage
POST   /api/reports/generate
GET    /api/reports/schedule

4.4 Security Implementation

4.4.1 Environment Configuration

# Authentication
ADMIN_PASSWORD_HASH=$2b$12$... # bcrypt hash
JWT_SECRET=<random-64-char-string>
SESSION_TIMEOUT=1800 # 30 minutes

# IP Restrictions
ALLOWED_IPS=192.168.1.0/24,10.0.0.5
ENABLE_IP_RESTRICTION=true

# MinIO Configuration
DEFAULT_MINIO_ALIAS=kopiaminio
MINIO_ENDPOINT=https://minio.example.com
MINIO_ACCESS_KEY=<encrypted>
MINIO_SECRET_KEY=<encrypted>

# Email Configuration (for reports)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=kopiabackup@example.com
SMTP_PASS=<encrypted>
REPORT_RECIPIENT=info@example.com

# Application
PORT=3000
NODE_ENV=production
LOG_LEVEL=info

4.4.2 Security Headers

// Helmet.js configuration
app.use(helmet({
  contentSecurityPolicy: {
    directives: {
      defaultSrc: ["'self'"],
      styleSrc: ["'self'", "'unsafe-inline'"],
      scriptSrc: ["'self'"],
      imgSrc: ["'self'", "data:", "https:"],
    },
  },
  hsts: {
    maxAge: 31536000,
    includeSubDomains: true,
    preload: true,
  },
}));

4.5 Database Schema (Optional)

If persistent storage is needed beyond MinIO:

-- Audit Log
CREATE TABLE audit_log (
  id SERIAL PRIMARY KEY,
  timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  user_ip VARCHAR(45),
  action VARCHAR(100),
  resource_type VARCHAR(50),
  resource_name VARCHAR(255),
  status VARCHAR(20),
  details JSONB
);

-- Report Schedule
CREATE TABLE report_schedule (
  id SERIAL PRIMARY KEY,
  name VARCHAR(100),
  cron_expression VARCHAR(100),
  recipients TEXT[],
  enabled BOOLEAN DEFAULT true,
  last_run TIMESTAMP,
  next_run TIMESTAMP
);

---

5. Implementation Plan

5.1 Project Structure

minio-webui/
├── backend/
│   ├── src/
│   │   ├── api/
│   │   │   ├── auth/
│   │   │   ├── buckets/
│   │   │   ├── users/
│   │   │   ├── policies/
│   │   │   └── reports/
│   │   ├── middleware/
│   │   │   ├── auth.middleware.js
│   │   │   ├── ipFilter.middleware.js
│   │   │   └── errorHandler.middleware.js
│   │   ├── services/
│   │   │   ├── minio.service.js
│   │   │   ├── auth.service.js
│   │   │   └── report.service.js
│   │   ├── utils/
│   │   │   ├── encryption.js
│   │   │   ├── validation.js
│   │   │   └── logger.js
│   │   ├── config/
│   │   │   └── index.js
│   │   └── app.js
│   ├── tests/
│   ├── package.json
│   └── .env.example
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── Layout/
│   │   │   ├── Buckets/
│   │   │   ├── Users/
│   │   │   ├── Policies/
│   │   │   └── Reports/
│   │   ├── hooks/
│   │   ├── services/
│   │   ├── store/
│   │   ├── utils/
│   │   └── App.tsx
│   ├── public/
│   ├── package.json
│   └── tsconfig.json
├── docker/
│   ├── Dockerfile.backend
│   ├── Dockerfile.frontend
│   └── docker-compose.yml
├── nginx/
│   └── default.conf
├── scripts/
│   ├── setup.sh
│   └── deploy.sh
└── README.md

5.2 Development Phases

Phase 1: Foundation (Week 1-2)

• Project setup and configuration
• Authentication system
• IP restriction middleware
• Basic API structure
• Frontend scaffolding

Phase 2: Core Features (Week 3-4)

• Bucket management API and UI
• User creation workflow
• Policy management system
• MinIO service integration

Phase 3: Advanced Features (Week 5-6)

• Storage monitoring dashboard
• Report generation system
• Email integration
• Alias management

Phase 4: Polish & Security (Week 7-8)

• Security audit and penetration testing
• Performance optimization
• Error handling improvements
• Documentation completion
• Deployment automation

5.3 Testing Strategy

Unit Tests

• Service layer: 90% coverage
• API endpoints: 85% coverage
• Utility functions: 100% coverage

Integration Tests

• MinIO CLI command execution
• Authentication flow
• Report generation

E2E Tests

• Critical user journeys
• Bucket creation workflow
• User management flow
• Report scheduling

Security Tests

• OWASP Top 10 compliance
• Penetration testing
• Dependency scanning
• Static code analysis

---

6. Deployment & Operations

6.1 Deployment Strategy

Production Deployment

1. Use Docker containers for consistency
2. Nginx reverse proxy with SSL
3. PM2 for Node.js process management
4. Automated backup of configuration
5. Blue-green deployment for zero downtime

Monitoring

• Application metrics (Prometheus)
• Error tracking (Sentry)
• Uptime monitoring (UptimeRobot)
• Log aggregation (ELK stack optional)

6.2 Maintenance

Regular Tasks

• Weekly dependency updates
• Monthly security patches
• Quarterly feature reviews
• Annual penetration testing

Backup Strategy

• Daily configuration backup
• Weekly audit log export
• Monthly full system backup

---

7. Risk Analysis

7.1 Technical Risks

Risk	Impact	Probability	Mitigation
MinIO CLI changes	High	Low	Version pinning, compatibility tests
Performance degradation	Medium	Medium	Caching, pagination, monitoring
Security breach	High	Low	Regular audits, minimal attack surface

7.2 Business Risks

Risk	Impact	Probability	Mitigation
User adoption	Medium	Low	Intuitive UI, training materials
Feature creep	Medium	High	Strict scope management
Maintenance burden	Low	Medium	Good documentation, automation

---

8. Success Criteria

8.1 Launch Criteria

• All core features implemented
• Security audit passed
• Performance benchmarks met
• Documentation complete
• User training conducted

8.2 Post-Launch Metrics

• User satisfaction score > 4.5/5
• Support ticket reduction > 80%
• System uptime > 99.9%
• Average task completion < 5 minutes

---

9. Appendices

9.1 MinIO CLI Reference

Key commands used by the WebUI:

mc mb ALIAS/BUCKET
mc admin user add ALIAS USERNAME PASSWORD
mc admin policy create ALIAS POLICYNAME policy.json
mc admin policy attach ALIAS POLICYNAME --user USERNAME
mc du --json ALIAS/BUCKET
mc ls ALIAS
mc admin user list ALIAS

9.2 Security Compliance

• GDPR compliance for audit logs
• SOC 2 Type II considerations
• ISO 27001 alignment

9.3 Future Enhancements

• Multi-tenant support
• LDAP/AD integration
• Advanced reporting dashboard
• Mobile application
• Kubernetes operator integration

---

Document Control:

• Author: System Architect
• Reviewers: Security Team, DevOps Team, Product Management
• Approval: CTO
• Next Review: Q2 2025