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

- **🚀 Quick Start Wizard**
  - One-click setup for bucket, user, and policy
  - Step-by-step guided configuration
  - Automatic credential generation
  - Built-in best practices

- **🪣 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

### Option 1: Interactive Quick Start Script

```bash
./scripts/quickstart.sh
```

This will:
- Check and start all services
- Guide you through initial setup
- Create your first bucket and user
- Provide connection details

### Option 2: Manual Setup

#### 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
# Option 1: Use the development script
./scripts/dev.sh

# Option 2: Manual start
# Terminal 1 - Backend
cd backend
PORT=7510 npm run dev

# Terminal 2 - Frontend  
cd frontend
PORT=7511 npm start
```

Access at: 
- Frontend: http://localhost:7511
- Backend API: http://localhost:7510

#### Production Mode (Docker)

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

Access at: http://localhost:7511 (or configured port)

## Configuration

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

### Port Configuration

Default ports:
- Backend API: 7510 (not 8080)
- Frontend UI: 7511 (development) or 3000 (React default)
- MinIO: 9000

**Important**: The frontend is configured to use relative API URLs. If you're running the backend on a different port or host, set the `REACT_APP_API_URL` environment variable:

```bash
# For development with custom backend URL
REACT_APP_API_URL=http://localhost:7510 npm start
```

To use different ports, see [Port Configuration Guide](docs/PORT_CONFIGURATION.md).

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

### Manual Password Hash Generation

If you need to generate the password hash manually (instead of using the setup script):

#### Method 1: Using Node.js

```bash
# Install bcrypt globally
npm install -g bcrypt-cli

# Generate hash (will prompt for password)
bcrypt-cli hash

# Or with inline password (be careful with shell history)
node -e "const bcrypt = require('bcrypt'); bcrypt.hash('YOUR_PASSWORD', 12).then(console.log)"
```

#### Method 2: Using Python

```bash
# Install bcrypt
pip install bcrypt

# Generate hash
python3 -c "import bcrypt; password = b'YOUR_PASSWORD'; print(bcrypt.hashpw(password, bcrypt.gensalt(rounds=12)).decode())"
```

#### Method 3: Using Docker

```bash
# One-liner using Node.js in Docker
docker run --rm -it node:alpine sh -c "npm install bcrypt && node -e \"require('bcrypt').hash('YOUR_PASSWORD', 12).then(console.log)\""
```

### JWT Secret Generation

Generate a secure JWT secret:

#### Method 1: Using OpenSSL

```bash
# Generate 64-character random string
openssl rand -base64 64 | tr -d '\n'
```

#### Method 2: Using Node.js

```bash
# Generate crypto-random string
node -e "console.log(require('crypto').randomBytes(64).toString('base64'))"
```

#### Method 3: Using Python

```bash
# Generate secure random string
python3 -c "import secrets; print(secrets.token_urlsafe(64))"
```

#### Method 4: Using /dev/urandom

```bash
# Generate from random device
head -c 64 /dev/urandom | base64 | tr -d '\n'
```

### Example .env Configuration

After generating your password hash and JWT secret:

```env
# Example with generated values
ADMIN_PASSWORD_HASH=$2b$12$YKkb7VCztpTQ5eRQwfBfKuP0kziOlLXdH8kKDP3ZbQfCPwF.EAYmS
JWT_SECRET=Km5F2p9kXx7Nw3Qr8vBz4Ht6Lj9Mn2Sf5Yd8Gc3Vb7Nx4Wq9Rt6Yh3Kp8Zx2Cv5
```

**Security Notes:**
- Never commit actual passwords or secrets to version control
- Use at least 12 rounds for bcrypt (default in examples above)
- JWT secrets should be at least 256 bits (32 bytes) of entropy
- Store the `.env` file securely with restricted permissions: `chmod 600 .env`

### Getting MinIO Access Keys

To connect to your MinIO server, you need the access key and secret key. Here's how to obtain them:

#### Method 1: From MinIO Console (Web UI)

1. Access your MinIO Console at `http://YOUR_MINIO_SERVER:9001`
2. Login with your root credentials
3. Navigate to **Identity** → **Service Accounts**
4. Click **Create Service Account**
5. Save the generated Access Key and Secret Key

#### Method 2: Using MinIO Client (mc)

```bash
# First, configure your MinIO alias if not already done
mc alias set myminio https://YOUR_MINIO_SERVER ROOTUSER ROOTPASSWORD

# Create a new service account
mc admin user svcacct add myminio YOUR_USERNAME

# This will output:
# Access Key: XXXXXXXXXXXXXXXXXXXX
# Secret Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
```

#### Method 3: From MinIO Server Startup

If you're running MinIO server locally:

```bash
# Default credentials when starting MinIO
export MINIO_ROOT_USER=minioadmin
export MINIO_ROOT_PASSWORD=minioadmin
minio server /data

# Or check existing environment variables
echo $MINIO_ROOT_USER
echo $MINIO_ROOT_PASSWORD
```

#### Method 4: From Docker/Docker Compose

If MinIO is running in Docker:

```bash
# Check docker-compose.yml for environment variables
grep -E "MINIO_ROOT_USER|MINIO_ROOT_PASSWORD" docker-compose.yml

# Or inspect running container
docker inspect <minio-container-name> | grep -E "MINIO_ROOT_USER|MINIO_ROOT_PASSWORD"
```

#### Method 5: From Kubernetes Secrets

If MinIO is running in Kubernetes:

```bash
# Get secret name
kubectl get secrets -n <namespace> | grep minio

# Decode the secret
kubectl get secret <minio-secret-name> -n <namespace> -o jsonpath='{.data.accesskey}' | base64 -d
kubectl get secret <minio-secret-name> -n <namespace> -o jsonpath='{.data.secretkey}' | base64 -d
```

#### Best Practices for MinIO Credentials

1. **Don't use root credentials**: Create a dedicated service account for the WebUI
2. **Limit permissions**: Create a policy that only allows necessary operations
3. **Rotate regularly**: Change service account credentials periodically
4. **Use environment variables**: Store credentials in environment variables, not in code

Example of creating a limited service account for MinIO WebUI:

```bash
# Create a policy for WebUI operations
mc admin policy create myminio webui-policy /path/to/policy.json

# Create a user and attach the policy
mc admin user add myminio webui-user webui-password
mc admin policy attach myminio webui-policy --user webui-user

# Or create a service account for an existing user
mc admin user svcacct add myminio webui-user
```

Example policy for MinIO WebUI (save as `webui-policy.json`):

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:ListAllMyBuckets",
        "s3:CreateBucket",
        "s3:DeleteBucket",
        "s3:GetBucketLocation",
        "s3:ListBucket",
        "s3:PutBucketPolicy",
        "s3:GetBucketPolicy",
        "admin:*"
      ],
      "Resource": ["arn:aws:s3:::*"]
    }
  ]
}
```

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

### Command-Line Tools

#### Create Bucket with User Script

```bash
./scripts/create-bucket-with-user.sh -b my-bucket -u my-user -p readwrite
```

Options:
- `-b, --bucket <name>`: Bucket name (auto-generated if not specified)
- `-u, --user <name>`: User name (auto-generated if not specified)
- `-p, --policy <type>`: Policy type: `readonly`, `writeonly`, `readwrite` (default)
- `-a, --api-url <url>`: API URL (default: http://localhost:7510)
- `--admin-user <user>`: Admin username for authentication
- `--admin-pass <pass>`: Admin password for authentication

#### Quick Start Script

```bash
./scripts/quickstart.sh
```

This interactive script will:
1. Check if services are running
2. Optionally start services using docker-compose
3. Guide you through creating an initial bucket and user
4. Provide MinIO CLI commands for testing

### Web Interface

#### Quick Start Wizard

Click the "Quick Start" button on the dashboard for a guided setup that will:
- Create a bucket
- Set up a user with secure password
- Configure appropriate access policies
- Provide ready-to-use credentials

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