minio-webui/PASSWORD_GENERATION.md

# Password Generation Guide for MinIO WebUI

## Quick Start

### Method 1: Simple Command (Recommended)

```bash
cd backend
npm run hash-password YourSecurePassword123!
```

This will output:
```
=== Generated Password Hash ===
ADMIN_PASSWORD_HASH=$2b$12$...your.hash.here...

Copy the above line to your .env file
```

### Method 2: Interactive Mode

```bash
cd backend
npm run generate-password
```

This will:
- Prompt you for a password (hidden input)
- Generate the bcrypt hash
- Show you the hash to copy to your .env file
- Verify the hash works correctly

## Docker Usage

If you're using Docker, you can run the password generator inside the container:

```bash
# Method 1: Quick hash
docker exec -it minio-webui-backend npm run hash-password YourPassword123!

# Method 2: Interactive
docker exec -it minio-webui-backend npm run generate-password
```

## Password Requirements

Your password should meet these criteria:
- Minimum 8 characters
- At least one uppercase letter (A-Z)
- At least one lowercase letter (a-z)
- At least one number (0-9)
- At least one special character (!@#$%^&* etc.)

## Example Passwords

Good passwords:
- `MySecure@Pass123`
- `Admin#2024!Strong`
- `MinIO$WebUI&Safe99`

## Step-by-Step Instructions

1. **Navigate to backend directory:**
   ```bash
   cd backend
   ```

2. **Generate your password hash:**
   ```bash
   npm run hash-password MyChosenPassword123!
   ```

3. **Copy the output** (it will look like this):
   ```
   ADMIN_PASSWORD_HASH=$2b$12$abcdefghijklmnopqrstuvwxyz...
   ```

4. **Add to your .env file:**
   ```bash
   # Edit your .env file
   nano ../.env
   
   # Or append directly
   echo "ADMIN_PASSWORD_HASH=\$2b\$12\$your_hash_here" >> ../.env
   ```

5. **Restart the backend:**
   ```bash
   # If using Docker
   docker-compose restart backend
   
   # If running locally
   npm start
   ```

## Troubleshooting

### "bcrypt: command not found"

The script uses the Node.js bcrypt library, not the system bcrypt. Make sure you're in the backend directory and have run `npm install`.

### "Cannot find module 'bcrypt'"

Install dependencies first:
```bash
cd backend
npm install
```

### Hash not working

1. Make sure you copied the entire hash including the `$2b$12$` prefix
2. Check for any extra spaces or line breaks
3. Ensure the .env file is in the project root directory
4. Try generating a new hash

### Special characters in password

If your password contains special shell characters, wrap it in single quotes:
```bash
npm run hash-password 'My$uper!Pass@123'
```

## Security Notes

1. **Never commit your .env file** to version control
2. **Use strong passwords** - the hash is only as secure as your password
3. **Change default passwords** immediately in production
4. **Store .env securely** with appropriate file permissions:
   ```bash
   chmod 600 .env
   ```

## Advanced Usage

### Custom Salt Rounds

The scripts use 12 salt rounds by default (recommended). If you need to change this, edit the script:

```javascript
const saltRounds = 12; // Change this value if needed
```

Higher numbers are more secure but slower to compute.

### Verify a Hash

To verify if a password matches a hash:

```javascript
// In Node.js
const bcrypt = require('bcrypt');
const isValid = await bcrypt.compare('YourPassword', '$2b$12$...');
console.log(isValid); // true or false
```

## Integration with MinIO WebUI

Once you've set the `ADMIN_PASSWORD_HASH` in your .env file:

1. Start/restart the application
2. Navigate to the login page
3. Username: `admin` (fixed)
4. Password: The password you used to generate the hash

The application will compare your entered password with the stored hash for authentication.