Paul Nothaft
6beb4ae03c
continuous-integration/drone/push Build is passing
- Add detailed logging for password verification to diagnose auth issues - Validate bcrypt hash format before attempting comparison - Use /tmp/minio-webui-temp as default temp directory (Docker-prepared) - Add comment about escaping $ in bcrypt hashes for docker-compose
108 lines
3.5 KiB
Markdown
108 lines
3.5 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
MinIO WebUI is a secure web interface for managing MinIO object storage. It's a monorepo with separate frontend (React/TypeScript) and backend (Express/Node.js) applications that communicate via REST API.
|
|
|
|
## Development Commands
|
|
|
|
### Backend (from `/backend`)
|
|
```bash
|
|
npm run dev # Development with nodemon (hot reload)
|
|
npm run dev:node # Development with Node.js --watch
|
|
npm start # Production
|
|
npm test # Jest tests with coverage
|
|
npm run lint # ESLint check
|
|
npm run lint:fix # ESLint auto-fix
|
|
```
|
|
|
|
### Frontend (from `/frontend`)
|
|
```bash
|
|
npm start # Development server (port 7511)
|
|
npm run build # Production build
|
|
npm test # React Testing Library tests
|
|
npm run lint # ESLint check
|
|
npm run lint:fix # ESLint auto-fix
|
|
```
|
|
|
|
### Full Stack Development
|
|
```bash
|
|
./dev.sh # Start both backend and frontend
|
|
./scripts/quickstart.sh # Interactive setup wizard
|
|
./scripts/setup.sh # Initial project setup
|
|
```
|
|
|
|
### Docker
|
|
```bash
|
|
docker-compose up -d # Start all services
|
|
docker-compose --profile proxy up -d # Start with Nginx SSL proxy
|
|
docker-compose logs -f # View logs
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Browser (React) → Nginx (optional SSL) → Express API → MinIO CLI (mc) → MinIO Server
|
|
```
|
|
|
|
### Backend (`/backend`)
|
|
- **Entry**: `src/app.js`
|
|
- **Services**: `src/services/` - Business logic (minio.service.js, auth.service.js, report.service.js)
|
|
- **Routes**: `src/api/` - REST endpoints (auth/, buckets/, users/, policies/, reports/)
|
|
- **Middleware**: `src/middleware/` - Auth, IP filtering, error handling
|
|
- **Config**: `src/config/index.js` - Environment configuration
|
|
|
|
### Frontend (`/frontend`)
|
|
- **Entry**: `src/index.tsx` → `src/App.tsx`
|
|
- **Components**: `src/components/` - Feature-based organization (Auth/, Buckets/, Users/, etc.)
|
|
- **State**: `src/store/authStore.ts` - Zustand for auth state with persistence
|
|
- **API**: `src/services/api.ts` - Axios instance
|
|
- **i18n**: `src/i18n.ts` - English and German translations in `src/locales/`
|
|
|
|
### Key Patterns
|
|
- Backend uses MinIO CLI (`mc`) commands via child processes, not MinIO SDK
|
|
- JWT tokens stored in httpOnly cookies with IP binding
|
|
- Frontend proxies to backend at `http://localhost:7510` (see `frontend/package.json` proxy setting)
|
|
- Policy files are created temporarily in `backend/temp/` (falls back to OS temp on permission issues)
|
|
|
|
## Ports
|
|
|
|
- Backend API: 7510
|
|
- Frontend Dev: 7511
|
|
- Frontend Prod: 3000
|
|
- MinIO: 9000 (default)
|
|
|
|
## Environment Configuration
|
|
|
|
The `.env` file (created by `./scripts/setup.sh`) requires:
|
|
- `ADMIN_PASSWORD_HASH` - bcrypt hash (12 rounds)
|
|
- `JWT_SECRET` - Session signing key
|
|
- `DEFAULT_MINIO_ALIAS` - Typically `kopiaminio`
|
|
- `MINIO_ENDPOINT`, `MINIO_ACCESS_KEY`, `MINIO_SECRET_KEY`
|
|
|
|
Generate password hash: `cd backend && npm run hash-password`
|
|
|
|
## Security Implementation
|
|
|
|
- Rate limiting: 100 req/15min general, 5 req/15min for auth
|
|
- IP whitelist via `ALLOWED_IPS` (CIDR notation supported)
|
|
- All operations logged to `logs/` with daily rotation
|
|
- CSRF protection with secure cookies
|
|
- Helmet.js for HTTP security headers
|
|
|
|
## Testing
|
|
|
|
Backend tests use Jest + Supertest. Frontend tests use React Testing Library.
|
|
|
|
Run a single backend test:
|
|
```bash
|
|
cd backend && npm test -- --testPathPattern="auth"
|
|
```
|
|
|
|
Run frontend tests in watch mode:
|
|
```bash
|
|
cd frontend && npm test
|
|
```
|