12 KiB
Garage Web UI - Desarrollo
Esta guía te ayudará a configurar el entorno de desarrollo para Garage Web UI con hot reload y todas las funcionalidades avanzadas.
🚀 Quick Start
Opción 1: Docker (Recomendado)
# Clona el repositorio
git clone https://github.com/khairul169/garage-webui.git
cd garage-webui
# Inicia el entorno completo de desarrollo
npm run dev:docker
# O por separado:
npm run dev:docker:frontend # Solo frontend
npm run dev:docker:backend # Solo backend
npm run dev:docker:fullstack # Todo en un contenedor
Opción 2: Local
# Instalar dependencias
pnpm install
npm run install:backend
# Desarrollo local (requiere Garage corriendo)
npm run dev
📁 Estructura del Proyecto
garage-webui/
├── src/ # Frontend React + TypeScript
│ ├── components/ # Componentes reutilizables
│ ├── pages/ # Páginas principales
│ │ ├── admin/ # Dashboard de administración
│ │ ├── auth/ # Autenticación
│ │ ├── buckets/ # Gestión de buckets
│ │ ├── cluster/ # Gestión del clúster
│ │ └── keys/ # Gestión de keys
│ ├── hooks/ # Custom hooks
│ ├── types/ # TypeScript types
│ └── lib/ # Utilidades
├── backend/ # Backend Go
│ ├── middleware/ # Middleware de seguridad
│ ├── router/ # Endpoints API
│ ├── schema/ # Modelos de datos
│ └── utils/ # Utilidades del servidor
├── docker-compose.dev.yml # Entorno de desarrollo
├── Dockerfile.dev # Dockerfile para desarrollo
└── README.dev.md # Esta documentación
🛠️ Configuración del Entorno
Variables de Entorno
Crea un archivo garage.toml
para Garage (ejemplo mínimo):
metadata_dir = "/var/lib/garage/meta"
data_dir = "/var/lib/garage/data"
db_engine = "sqlite"
replication_factor = 1
rpc_bind_addr = "[::]:3901"
rpc_public_addr = "127.0.0.1:3901"
rpc_secret = "1799bccfd7411abbccc9a3f8a0ccc314f5d0d9690e9a2cc4de5ba8faa24a3ee2"
[s3_api]
s3_region = "garage"
api_bind_addr = "[::]:3900"
root_domain = ".s3.garage.localhost"
[admin]
api_bind_addr = "[::]:3903"
admin_token = "admin-token-change-me"
metrics_token = "metrics-token-change-me"
Variables de Entorno para Desarrollo
El proyecto incluye configuración automática para desarrollo:
Frontend (.env.development):
VITE_API_URL=http://localhost:3909
VITE_MODE=development
VITE_DEBUG=true
Backend (docker-compose.dev.yml):
CONFIG_PATH=/etc/garage.toml
API_BASE_URL=http://garage:3903
S3_ENDPOINT_URL=http://garage:3900
DATA_DIR=/app/data
CORS_ALLOWED_ORIGINS=http://localhost:5173,http://127.0.0.1:5173
RATE_LIMIT_REQUESTS=1000
RATE_LIMIT_WINDOW=1m
🔥 Hot Reload
Frontend (React)
- Puerto: 5173
- Hot Module Replacement: Activado automáticamente
- Proxy API:
/api/*
→http://localhost:3909
- File Watching: Optimizado para Docker con polling
Backend (Go)
- Puerto: 3909
- Herramienta: Air (similar a nodemon para Node.js)
- Auto-rebuild: Al cambiar archivos
.go
- Configuración:
backend/.air.toml
🐳 Opciones de Docker
1. Frontend + Backend Separados (Recomendado)
# Inicia Garage + Frontend + Backend en contenedores separados
npm run dev:docker
# Accede a:
# - Frontend: http://localhost:5173 (con HMR)
# - Backend API: http://localhost:3909
# - Garage S3: http://localhost:3900
# - Garage Admin: http://localhost:3903
Ventajas:
- ✅ Mejor aislamiento
- ✅ Hot reload independiente
- ✅ Fácil debugging
- ✅ Logs separados
2. Frontend Solo
npm run dev:docker:frontend
Útil cuando quieres desarrollar solo el frontend con un backend en producción.
3. Backend Solo
npm run dev:docker:backend
Útil para desarrollo de API con frontend en producción.
4. Fullstack (Un Solo Contenedor)
npm run dev:docker:fullstack
Puertos alternativos: Frontend: 5174, Backend: 3910
📝 Scripts Disponibles
Desarrollo
npm run dev # Local: Frontend + Backend
npm run dev:client # Solo frontend local
npm run dev:server # Solo backend local
npm run dev:docker # Docker: Todo el entorno
npm run dev:docker:frontend # Docker: Solo frontend
npm run dev:docker:backend # Docker: Solo backend
npm run dev:docker:fullstack # Docker: Fullstack
Build y Testing
npm run build # Build de producción
npm run build:dev # Build de desarrollo
npm run type-check # Verificar tipos TypeScript
npm run lint # Linter
npm run lint:fix # Fix automático del linter
npm run test:backend # Tests del backend Go
Backend
npm run install:backend # Instalar dependencias Go
npm run build:backend # Build del backend
Limpieza
npm run clean # Limpiar cache y builds
npm run dev:docker:clean # Limpiar contenedores y volúmenes
🔐 Sistema de Autenticación
Usuario por Defecto
Al iniciar por primera vez, se crea automáticamente:
- Usuario:
admin
- Contraseña:
admin
- Rol: Administrador
⚠️ IMPORTANTE: Cambia la contraseña después del primer login.
Roles Disponibles
- Admin: Acceso completo al sistema
- Tenant Admin: Administración de su tenant
- User: Usuario básico con permisos limitados
- ReadOnly: Solo lectura
🎯 Funcionalidades de Desarrollo
Dashboard de Administración
- ✅ Gestión completa de usuarios
- ✅ Sistema de tenants (multi-tenancy)
- ✅ Roles y permisos granulares
- ✅ Configuración dinámica de S3
- ✅ Monitoreo del sistema
Seguridad Implementada
- ✅ Autenticación JWT con sessiones
- ✅ Rate limiting configurable
- ✅ Headers de seguridad (CORS, XSS, etc.)
- ✅ Cifrado bcrypt para contraseñas
- ✅ Middleware de autorización
Base de Datos
- ✅ Persistencia en JSON local
- ✅ Thread-safe operations
- ✅ Backup automático
- ✅ Migration desde configuración legacy
🐛 Debugging
Logs del Frontend
# Ver logs del frontend
docker-compose -f docker-compose.dev.yml logs -f webui-frontend
# O desde el navegador
# Abre DevTools → Console
Logs del Backend
# Ver logs del backend
docker-compose -f docker-compose.dev.yml logs -f webui-backend
# Ver logs de Garage
docker-compose -f docker-compose.dev.yml logs -f garage
Debugging del Backend Go
# Ejecutar en contenedor para debugging
docker-compose -f docker-compose.dev.yml exec webui-backend sh
# Ver estado de la base de datos
cat /app/data/database.json
# Logs de compilación
cat /app/build-errors.log
📊 Monitoreo
Endpoints Útiles para Desarrollo
GET /api/auth/status
- Estado de autenticaciónGET /api/s3/status
- Estado del sistema S3GET /api/s3/config
- Configuración actualPOST /api/s3/test
- Test de conectividadGET /api/users
- Lista de usuarios (admin)GET /api/tenants
- Lista de tenants (admin)
Health Checks
- Garage:
http://localhost:3903/status
- WebUI Backend:
http://localhost:3909/api/s3/status
🚨 Troubleshooting
El frontend no se actualiza automáticamente
# Verificar que el polling esté habilitado
# En vite.config.ts debe estar:
watch: {
usePolling: true,
interval: 100,
}
El backend no se recarga
# Verificar que Air esté corriendo
docker-compose -f docker-compose.dev.yml logs webui-backend
# Debe mostrar: "watching .go files"
Problemas de conectividad
# Verificar que todos los servicios estén corriendo
docker-compose -f docker-compose.dev.yml ps
# Verificar conectividad a Garage
curl http://localhost:3903/status
Limpiar estado corrupto
# Limpiar todo y empezar de nuevo
npm run dev:docker:clean
docker system prune -a
npm run dev:docker
Base de datos corrupta
# Backup automático en dev-data/
cp dev-data/backup-database.json backend/data/database.json
# O eliminar para recrear usuario admin
rm backend/data/database.json
🎨 Desarrollo del Frontend
Estructura de Componentes
src/components/ui/
- Componentes base (Button, Input, etc.)src/components/containers/
- Contenedores (Sidebar, Theme, etc.)src/components/layouts/
- Layouts de páginasrc/pages/
- Páginas específicas
Estado Global
- React Query: Cache de API y estado servidor
- Zustand: Estado global mínimo (theme, etc.)
- React Hook Form: Formularios con validación
Estilos
- Tailwind CSS: Utility-first CSS
- DaisyUI: Componentes pre-diseñados
- CSS Modules: Estilos específicos cuando es necesario
🔧 Desarrollo del Backend
Arquitectura
backend/
├── main.go # Entry point
├── router/ # Endpoints HTTP
│ ├── auth.go # Autenticación
│ ├── users.go # Gestión usuarios
│ ├── tenants.go # Gestión tenants
│ └── s3config.go # Configuración S3
├── middleware/ # Middleware HTTP
│ ├── auth.go # Autenticación
│ └── security.go # Seguridad (CORS, Rate limiting)
├── schema/ # Modelos de datos
├── utils/ # Utilidades
└── .air.toml # Configuración hot reload
Adding New Endpoints
// 1. Agregar al router (router/router.go)
users := &Users{}
router.HandleFunc("GET /users", users.GetAll)
// 2. Implementar handler (router/users.go)
func (u *Users) GetAll(w http.ResponseWriter, r *http.Request) {
// Verificar permisos
if !u.checkPermission(r, schema.PermissionReadUsers) {
utils.ResponseErrorStatus(w, nil, http.StatusForbidden)
return
}
// Lógica del endpoint
users, err := utils.DB.ListUsers()
if err != nil {
utils.ResponseError(w, err)
return
}
utils.ResponseSuccess(w, users)
}
🔒 Seguridad en Desarrollo
HTTPS Local (Opcional)
Para testing de características que requieren HTTPS:
# Generar certificados locales
mkcert localhost 127.0.0.1
# Actualizar vite.config.ts para usar HTTPS
server: {
https: {
key: fs.readFileSync('localhost-key.pem'),
cert: fs.readFileSync('localhost.pem'),
},
// ... resto de config
}
Variables de Entorno Sensibles
# NO commitear archivos con secretos reales
# Usar valores de desarrollo como:
rpc_secret = "dev-secret-not-for-production"
admin_token = "dev-admin-token"
📋 Checklist Pre-Commit
npm run type-check
pasa sin erroresnpm run lint
pasa sin erroresnpm run test:backend
pasa todos los tests- Hot reload funciona en frontend y backend
- Dashboard de admin funciona correctamente
- No hay secrets hardcodeados en el código
🚀 Deployment
Una vez que el desarrollo esté listo, usa el docker-compose.yml original para producción:
# Build de producción
npm run build
# Deploy con el docker-compose.yml original
docker-compose up --build
💡 Tips de Desarrollo
VS Code Extensions Recomendadas
- TypeScript Importer
- Tailwind CSS IntelliSense
- Go Extension
- Docker Extension
- Thunder Client (para testing de APIs)
Chrome Extensions Útiles
- React Developer Tools
- TanStack Query DevTools
¿Problemas? Abre un issue en el repositorio con:
- Comando que causó el problema
- Logs completos (
docker-compose logs
) - Sistema operativo y versión de Docker
- Pasos para reproducir