minio-webui/README.md

# MinIO WebUI

A secure, user-friendly web interface for managing MinIO storage infrastructure. Designed specifically for non-Linux administrators to easily manage buckets, users, and monitor storage usage.

## Features

- **🪣 Bucket Management**
  - Create buckets with automatic user creation
  - List and monitor bucket sizes
  - Delete empty buckets
  - Real-time storage statistics

- **👥 User Management**
  - Create users with bucket access
  - Automatic policy generation
  - User credential management
  - Enable/disable user accounts

- **📊 Storage Monitoring**
  - Real-time storage dashboard
  - Visual storage distribution charts
  - Weekly automated reports via email
  - Export reports in CSV/JSON formats

- **🔒 Security**
  - Encrypted password storage
  - JWT-based authentication
  - IP-based access restrictions
  - Audit logging for all operations
  - HTTPS support with SSL

- **🎯 Simple Interface**
  - Wizard-based workflows
  - Clear error messages
  - Mobile-responsive design
  - No Linux knowledge required

## Prerequisites

- Node.js 18+ and npm
- Docker and Docker Compose (for containerized deployment)
- MinIO Client (`mc`) installed
- Access to a MinIO server

## Quick Start

### 1. Clone the Repository

```bash
git clone <repository-url>
cd minio-webui
```

### 2. Run Setup Script

```bash
./scripts/setup.sh
```

The setup script will:
- Create `.env` configuration file
- Generate secure admin password
- Configure MinIO connection
- Install dependencies
- Build the frontend
- Optionally generate SSL certificates

**Important**: Save the generated admin password securely!

### 3. Start the Application

#### Development Mode

```bash
# Terminal 1 - Backend
cd backend
npm run dev

# Terminal 2 - Frontend
cd frontend
npm start
```

Access at: http://localhost:3000

#### Production Mode (Docker)

```bash
./scripts/deploy.sh
# Select option 1 for quick deployment
```

Access at: http://localhost

## Configuration

All configuration is managed through the `.env` file:

### Essential Settings

```env
# Admin password (bcrypt hash)
ADMIN_PASSWORD_HASH=$2b$12$...

# JWT secret for sessions
JWT_SECRET=your-secret-key

# MinIO connection
DEFAULT_MINIO_ALIAS=kopiaminio
MINIO_ENDPOINT=https://minio.example.com
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
```

### Security Settings

```env
# IP restrictions
ENABLE_IP_RESTRICTION=true
ALLOWED_IPS=192.168.1.0/24,10.0.0.5

# Session timeout (seconds)
SESSION_TIMEOUT=1800
```

### Email Settings (for reports)

```env
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
REPORT_RECIPIENT=info@example.com
```

## Usage Guide

### Creating a Bucket with User

1. Navigate to **Buckets** page
2. Click **Create Bucket**
3. Enter bucket name (e.g., `alice-bucket`)
4. Choose to create a user (enabled by default)
5. Enter username and password
6. Click **Create**
7. Save the displayed credentials securely

This creates:
- A new bucket
- A new MinIO user
- A policy granting full access to the bucket
- Automatic policy attachment

### Monitoring Storage

1. Navigate to **Reports** page
2. View real-time storage statistics
3. See visual distribution chart
4. Click **Send Report** to email current report
5. Click **CSV** or **JSON** to export data

### Weekly Automated Reports

Reports are automatically sent every Monday at midnight (configurable via `REPORT_SCHEDULE` in `.env`).

## Architecture

```
┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   Browser   │────▶│    Nginx     │────▶│  Express    │
│  (React)    │     │  (SSL/Proxy) │     │   (API)     │
└─────────────┘     └──────────────┘     └──────┬──────┘
                                                 │
                                                 ▼
                                         ┌─────────────┐
                                         │  MinIO CLI  │
                                         │    (mc)     │
                                         └──────┬──────┘
                                                │
                                                ▼
                                         ┌─────────────┐
                                         │   MinIO     │
                                         │   Server    │
                                         └─────────────┘
```

## Security Considerations

1. **Authentication**: Single admin user with bcrypt-hashed password
2. **Session Management**: JWT tokens with configurable timeout
3. **IP Restrictions**: Whitelist specific IPs or CIDR ranges
4. **HTTPS**: SSL/TLS encryption for production
5. **Audit Logging**: All operations are logged with timestamp and IP
6. **Input Validation**: Comprehensive validation on all inputs
7. **CSRF Protection**: Secure cookies and token validation

## Deployment

### Docker Deployment (Recommended)

```bash
# Quick deployment
docker-compose up -d

# Production with SSL
docker-compose --profile proxy up -d
```

### Manual Deployment

1. Build frontend: `cd frontend && npm run build`
2. Start backend: `cd backend && npm start`
3. Configure Nginx as reverse proxy
4. Set up SSL certificates
5. Configure firewall rules

### PM2 Deployment

```bash
# Install PM2
npm install -g pm2

# Start backend
cd backend
pm2 start src/app.js --name minio-webui

# Save PM2 configuration
pm2 save
pm2 startup
```

## Troubleshooting

### Common Issues

1. **"mc: command not found"**
   - Install MinIO client: https://min.io/docs/minio/linux/reference/minio-mc.html

2. **"Access Denied" error**
   - Check IP restrictions in `.env`
   - Verify your IP is whitelisted

3. **Cannot connect to MinIO**
   - Verify MinIO credentials in `.env`
   - Check MinIO server is accessible
   - Test with: `mc admin info YOUR_ALIAS`

4. **Email reports not sending**
   - Verify SMTP settings in `.env`
   - Check firewall allows SMTP port
   - Enable "less secure apps" for Gmail

### Logs

- Application logs: `logs/` directory
- Docker logs: `docker-compose logs -f`
- Audit logs: `logs/audit-*.log`

## Development

### Project Structure

```
minio-webui/
├── backend/          # Express.js API
├── frontend/         # React application
├── docker/           # Docker configurations
├── nginx/            # Nginx configurations
├── scripts/          # Setup and deployment scripts
├── logs/             # Application logs
└── ssl/              # SSL certificates
```

### API Endpoints

- `POST /api/auth/login` - Admin login
- `GET /api/buckets` - List buckets
- `POST /api/buckets/with-user` - Create bucket with user
- `GET /api/reports/storage` - Get storage report
- `POST /api/reports/generate` - Send email report

### Adding Features

1. Create new API endpoint in `backend/src/api/`
2. Add service logic in `backend/src/services/`
3. Create React component in `frontend/src/components/`
4. Update routing in `frontend/src/App.tsx`

## License

MIT License - see LICENSE file for details

## Support

For issues and feature requests, please create an issue in the repository.

## Acknowledgments

- Built with React, Node.js, and Material-UI
- Uses MinIO Client (mc) for storage operations
- Inspired by the need for simple MinIO management