khairul169/garage-webui
1
0
Fork 0
mirror of https://github.com/khairul169/garage-webui.git synced 2025-10-14 14:59:32 +07:00
Code Issues Actions Packages Projects Releases Wiki Activity
garage-webui/README.dev.md
Aluisco Ricardo 15a350370c Add auth and tenant function
2025-09-25 17:35:50 -03:00

12 KiB
Raw Blame History

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ón
  • GET /api/s3/status - Estado del sistema S3
  • GET /api/s3/config - Configuración actual
  • POST /api/s3/test - Test de conectividad
  • GET /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ágina
  • src/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 errores
  • npm run lint pasa sin errores
  • npm 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:

  1. Comando que causó el problema
  2. Logs completos (docker-compose logs)
  3. Sistema operativo y versión de Docker
  4. Pasos para reproducir