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

./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

git clone <repository-url>
cd minio-webui

2. Run Setup Script

./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

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

./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:

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

To use different ports, see Port Configuration Guide.

Essential Settings

# 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

# 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

# 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

# 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

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

Method 2: Using Node.js

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

Method 3: Using Python

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

Method 4: Using /dev/urandom

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

Example .env Configuration

After generating your password hash and JWT secret:

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

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

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

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

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

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

{
  "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

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

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

./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

./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)

# 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

# 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