minio-webui/CLAUDE.md

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)

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)

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

./dev.sh                     # Start both backend and frontend
./scripts/quickstart.sh      # Interactive setup wizard
./scripts/setup.sh           # Initial project setup

Docker

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:

cd backend && npm test -- --testPathPattern="auth"

Run frontend tests in watch mode:

cd frontend && npm test