mirror of
https://github.com/khairul169/garage-webui.git
synced 2025-10-14 14:59:32 +07:00
chore: remove outdated API documentation files
- Delete obsolete documentation files related to the Garage Admin API and upgrade report - Clean up project by removing unnecessary files to streamline maintenance and focus on current documentation
This commit is contained in:
Adekabang
parent
6eab387146
commit
166029fc5a
1210
docs/STYLE_GUIDE.md
1210
docs/STYLE_GUIDE.md
File diff suppressed because it is too large
Load Diff
@ -1,249 +0,0 @@
|
|||||||
# Garage Web UI API Alignment Task List
|
|
||||||
|
|
||||||
## Overview
|
|
||||||
|
|
||||||
This document outlines the tasks required to fully align the Garage Web UI implementation with the official [Garage Admin API v2 specification](https://garagehq.deuxfleurs.fr/api/garage-admin-v2.html).
|
|
||||||
|
|
||||||
**✅ Major Alignment Completed**: As of July 2025, all critical HTTP method and endpoint alignments have been completed, and the codebase has been fully cleaned of linting issues.
|
|
||||||
|
|
||||||
**Current Status**: 18/55+ official v2 endpoints implemented (33% coverage)
|
|
||||||
**Core Compliance**: ✅ **100% aligned** with official specification for implemented endpoints
|
|
||||||
**Code Quality**: ✅ **All ESLint issues resolved**
|
|
||||||
**Goal**: Continue expanding API coverage while maintaining full compliance
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔧 **High Priority: HTTP Method Alignment**
|
|
||||||
|
|
||||||
### Task 1: ✅ Verify and Align Delete Operations (COMPLETED)
|
|
||||||
- [x] **Research Official Specification**: Confirmed the exact HTTP methods specified for delete operations in the official docs
|
|
||||||
- [x] **Update AddBucketAlias Implementation**:
|
|
||||||
- Previous: `PUT /v2/PutBucketGlobalAlias`
|
|
||||||
- Current: `POST /v2/AddBucketAlias` (aligned with official specification)
|
|
||||||
- Parameters: `bucketId` and `globalAlias` in request body
|
|
||||||
- [x] **Update RemoveBucketAlias Implementation**:
|
|
||||||
- Previous: `DELETE /v2/DeleteBucketGlobalAlias`
|
|
||||||
- Current: `POST /v2/RemoveBucketAlias` (aligned with official specification)
|
|
||||||
- Parameters: `bucketId` and `globalAlias` in request body
|
|
||||||
- [x] **Update Frontend Hooks**: Modified `src/pages/buckets/manage/hooks.ts` to use correct endpoints
|
|
||||||
- [x] **Update Documentation**: Updated all documentation files to reflect official endpoint names
|
|
||||||
|
|
||||||
### Task 2: ✅ Review Other HTTP Methods (COMPLETED)
|
|
||||||
- [x] **Verify DeleteKey Method**:
|
|
||||||
- Previous: `DELETE /v2/DeleteKey?id={id}`
|
|
||||||
- Current: `POST /v2/DeleteKey/{id}` (aligned with official specification)
|
|
||||||
- Updated frontend hook in `src/pages/keys/hooks.ts`
|
|
||||||
- [x] **Verify DeleteBucket Method**:
|
|
||||||
- Previous: `DELETE /v2/DeleteBucket?id={id}`
|
|
||||||
- Current: `POST /v2/DeleteBucket/{id}` (aligned with official specification)
|
|
||||||
- Updated frontend hook in `src/pages/buckets/manage/hooks.ts`
|
|
||||||
- [x] **Update Frontend Hooks**: Modified both key and bucket hooks to use correct endpoints
|
|
||||||
- [x] **Update Documentation**: Updated all documentation to reflect official endpoint specifications
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📋 **Medium Priority: Missing Official Endpoints**
|
|
||||||
|
|
||||||
### Task 3: Implement Additional Cluster Management
|
|
||||||
- [ ] **Add GetClusterStatistics**: `GET /v2/GetClusterStatistics`
|
|
||||||
- Create hook in `src/pages/cluster/hooks.ts`
|
|
||||||
- Add UI component for cluster statistics display
|
|
||||||
- Integrate into cluster dashboard
|
|
||||||
- [ ] **Add PreviewClusterLayoutChanges**: `POST /v2/PreviewClusterLayoutChanges`
|
|
||||||
- Implement preview functionality before applying changes
|
|
||||||
- Add confirmation dialog with preview results
|
|
||||||
- [ ] **Add GetClusterLayoutHistory**: `GET /v2/GetClusterLayoutHistory`
|
|
||||||
- Create layout history viewer component
|
|
||||||
- Add navigation to view past layout versions
|
|
||||||
|
|
||||||
### Task 4: Implement Enhanced Bucket Features
|
|
||||||
- [ ] **Add CleanupIncompleteUploads**: `POST /v2/CleanupIncompleteUploads`
|
|
||||||
- Create cleanup functionality in bucket management
|
|
||||||
- Add scheduled/manual cleanup options
|
|
||||||
- [ ] **Add InspectObject**: `GET /v2/InspectObject`
|
|
||||||
- Integrate into object browser
|
|
||||||
- Add object inspection modal/page
|
|
||||||
- [ ] **Add Enhanced Bucket Operations**:
|
|
||||||
- [ ] `POST /v2/AddBucketAlias` (if different from current implementation)
|
|
||||||
- [ ] `POST /v2/RemoveBucketAlias` (if different from current implementation)
|
|
||||||
|
|
||||||
### Task 5: Implement Key Management Enhancements
|
|
||||||
- [ ] **Add GetKeyInfo**: `GET /v2/GetKeyInfo`
|
|
||||||
- Create key details page
|
|
||||||
- Show key capabilities, expiration, etc.
|
|
||||||
- [ ] **Add UpdateKey**: `POST /v2/UpdateKey/{id}`
|
|
||||||
- Add key editing functionality
|
|
||||||
- Allow updating permissions, expiration, name
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🚀 **Low Priority: Advanced Features**
|
|
||||||
|
|
||||||
### Task 6: Admin Token Management
|
|
||||||
- [ ] **Add Token Listing**: `GET /v2/ListAdminTokens`
|
|
||||||
- [ ] **Add Token Details**: `GET /v2/GetAdminTokenInfo`
|
|
||||||
- [ ] **Add Current Token Info**: `GET /v2/GetCurrentAdminTokenInfo`
|
|
||||||
- [ ] **Add Token Creation**: `POST /v2/CreateAdminToken`
|
|
||||||
- [ ] **Add Token Updates**: `POST /v2/UpdateAdminToken/{id}`
|
|
||||||
- [ ] **Add Token Deletion**: `POST /v2/DeleteAdminToken/{id}`
|
|
||||||
- [ ] **Create Admin Token Management UI**:
|
|
||||||
- Token listing page
|
|
||||||
- Token creation wizard
|
|
||||||
- Token permissions management
|
|
||||||
|
|
||||||
### Task 7: Node Management & Monitoring
|
|
||||||
- [ ] **Add Node Information**: `GET /v2/GetNodeInfo/{node}`
|
|
||||||
- [ ] **Add Node Statistics**: `GET /v2/GetNodeStatistics/{node}`
|
|
||||||
- [ ] **Add Metadata Snapshots**: `POST /v2/CreateMetadataSnapshot/{node}`
|
|
||||||
- [ ] **Add Repair Operations**: `POST /v2/LaunchRepairOperation/{node}`
|
|
||||||
- [ ] **Create Node Management UI**:
|
|
||||||
- Node dashboard with detailed information
|
|
||||||
- Repair operation scheduler
|
|
||||||
- Node health monitoring
|
|
||||||
|
|
||||||
### Task 8: Worker Process Management
|
|
||||||
- [ ] **Add Worker Listing**: `POST /v2/ListWorkers/{node}`
|
|
||||||
- [ ] **Add Worker Information**: `POST /v2/GetWorkerInfo/{node}`
|
|
||||||
- [ ] **Add Worker Variables**: `POST /v2/GetWorkerVariable/{node}`
|
|
||||||
- [ ] **Add Variable Setting**: `POST /v2/SetWorkerVariable/{node}`
|
|
||||||
- [ ] **Create Worker Management UI**:
|
|
||||||
- Worker process monitor
|
|
||||||
- Variable configuration interface
|
|
||||||
|
|
||||||
### Task 9: Block Management
|
|
||||||
- [ ] **Add Block Information**: `POST /v2/GetBlockInfo/{node}`
|
|
||||||
- [ ] **Add Block Error Listing**: `GET /v2/ListBlockErrors/{node}`
|
|
||||||
- [ ] **Add Block Resync**: `POST /v2/RetryBlockResync/{node}`
|
|
||||||
- [ ] **Add Block Purging**: `POST /v2/PurgeBlocks/{node}`
|
|
||||||
- [ ] **Create Block Management UI**:
|
|
||||||
- Block health dashboard
|
|
||||||
- Error resolution tools
|
|
||||||
- Maintenance operations interface
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🧪 **Testing & Validation Tasks**
|
|
||||||
|
|
||||||
### Task 10: Compatibility Testing
|
|
||||||
- [ ] **Test Against Multiple Garage Versions**:
|
|
||||||
- [ ] Test with Garage v2.0.x
|
|
||||||
- [ ] Test with latest Garage version
|
|
||||||
- [ ] Verify backward compatibility
|
|
||||||
- [ ] **API Method Validation**:
|
|
||||||
- [ ] Test all current endpoints with official methods
|
|
||||||
- [ ] Verify error handling consistency
|
|
||||||
- [ ] Check response format compliance
|
|
||||||
- [ ] **Integration Testing**:
|
|
||||||
- [ ] Test with real Garage clusters
|
|
||||||
- [ ] Validate cluster operations end-to-end
|
|
||||||
- [ ] Test authentication and authorization
|
|
||||||
|
|
||||||
### Task 11: Error Handling Alignment
|
|
||||||
- [ ] **Review Error Response Formats**: Ensure they match official specification
|
|
||||||
- [ ] **Update Error Messages**: Align with official API error codes and messages
|
|
||||||
- [ ] **Implement Proper Status Codes**: Verify all HTTP status codes match specification
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📚 **Documentation & Maintenance Tasks**
|
|
||||||
|
|
||||||
### Task 12: Documentation Updates
|
|
||||||
- [ ] **Update API Documentation**: Align all endpoint documentation with official specification
|
|
||||||
- [ ] **Add Implementation Notes**: Document any intentional deviations from official spec
|
|
||||||
- [ ] **Create Migration Guide**: Document changes needed for users upgrading
|
|
||||||
- [ ] **Update README**: Reflect full API v2 compliance status
|
|
||||||
|
|
||||||
### Task 13: Code Quality Improvements
|
|
||||||
- [ ] **Type Definition Updates**: Create proper TypeScript interfaces for all API responses
|
|
||||||
- [ ] **Error Handling Standardization**: Implement consistent error handling across all endpoints
|
|
||||||
- [ ] **Code Documentation**: Add comprehensive JSDoc comments to all API functions
|
|
||||||
- [ ] **Unit Testing**: Add tests for all API integration functions
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🎯 **Implementation Strategy**
|
|
||||||
|
|
||||||
### Phase 1: Core Alignment (Week 1-2)
|
|
||||||
1. Complete Tasks 1-2 (HTTP Method Alignment)
|
|
||||||
2. Implement Task 10 (Compatibility Testing)
|
|
||||||
3. Update documentation for changes
|
|
||||||
|
|
||||||
### Phase 2: Essential Features (Week 3-4)
|
|
||||||
1. Complete Task 3 (Additional Cluster Management)
|
|
||||||
2. Complete Task 4 (Enhanced Bucket Features)
|
|
||||||
3. Complete Task 5 (Key Management Enhancements)
|
|
||||||
|
|
||||||
### Phase 3: Advanced Features (Month 2)
|
|
||||||
1. Implement Tasks 6-9 based on user demand and priority
|
|
||||||
2. Complete comprehensive testing
|
|
||||||
3. Full documentation update
|
|
||||||
|
|
||||||
### Phase 4: Maintenance (Ongoing)
|
|
||||||
1. Monitor official API updates
|
|
||||||
2. Maintain compatibility with new Garage versions
|
|
||||||
3. Address user feedback and issues
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ✅ **Completion Criteria**
|
|
||||||
|
|
||||||
- [ ] All official v2 endpoints implemented (100% coverage)
|
|
||||||
- [ ] HTTP methods align with official specification (or documented deviations)
|
|
||||||
- [ ] Comprehensive test coverage for all endpoints
|
|
||||||
- [ ] Updated documentation reflecting full compliance
|
|
||||||
- [ ] Successful testing against multiple Garage versions
|
|
||||||
- [ ] User feedback incorporated and addressed
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📊 **ACHIEVEMENT SUMMARY**
|
|
||||||
|
|
||||||
### **Current Status (July 2025)**
|
|
||||||
- ✅ **18 Core API Endpoints**: Fully implemented and aligned
|
|
||||||
- ✅ **9 Custom Extensions**: Authentication, object browsing, file management
|
|
||||||
- ✅ **100% Code Quality**: All ESLint issues resolved
|
|
||||||
- ✅ **100% API Compliance**: All implemented endpoints match official specification
|
|
||||||
- ✅ **Production Ready**: Stable, tested, and performant
|
|
||||||
|
|
||||||
### **Next Milestones**
|
|
||||||
- 🎯 **Expand API Coverage**: Implement additional v2 endpoints (Admin tokens, Node management)
|
|
||||||
- 🎯 **Enhanced Features**: Add advanced cluster monitoring and management tools
|
|
||||||
- 🎯 **Performance**: Continue optimizing for large-scale deployments
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**Last Updated**: July 2025
|
|
||||||
**Next Review**: Quarterly or when official API specification changes
|
|
||||||
**Status**: ✅ **Core objectives achieved - Moving to enhancement phase**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ✅ **COMPLETED TASKS (July 2025)**
|
|
||||||
|
|
||||||
### **Phase 1: Critical API Alignment ✅ COMPLETED**
|
|
||||||
|
|
||||||
- [x] **HTTP Method Alignment**: All delete and alias operations now use correct POST methods
|
|
||||||
- [x] **Endpoint URL Format**: All endpoints use correct query parameter format (`?id={id}`)
|
|
||||||
- [x] **Request Body Format**: All POST requests use proper JSON body structure
|
|
||||||
- [x] **API Documentation**: All documentation updated to reflect official specification
|
|
||||||
- [x] **Frontend Hook Updates**: All React hooks updated with correct endpoints
|
|
||||||
|
|
||||||
### **Phase 2: Code Quality & Stability ✅ COMPLETED**
|
|
||||||
|
|
||||||
- [x] **TypeScript Improvements**: Removed all `any` types, improved type safety
|
|
||||||
- [x] **ESLint Resolution**: Fixed all 15 linting errors and warnings
|
|
||||||
- [x] **React Best Practices**: Resolved controlled/uncontrolled input issues
|
|
||||||
- [x] **Component Keys**: Added proper `key` props to all list items
|
|
||||||
- [x] **Form Validation**: Fixed form control issues and default values
|
|
||||||
- [x] **Mobile UX**: Resolved sidebar toggle issues on mobile devices
|
|
||||||
|
|
||||||
### **Phase 3: API Specification Compliance ✅ COMPLETED**
|
|
||||||
|
|
||||||
- [x] **Bucket Operations**: `AddBucketAlias`, `RemoveBucketAlias`, `DeleteBucket`
|
|
||||||
- [x] **Key Operations**: `DeleteKey` with proper query parameter format
|
|
||||||
- [x] **Official Documentation Review**: Verified against live API documentation
|
|
||||||
- [x] **Error Handling**: Resolved 400 Bad Request issues with corrected endpoints
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🚀 **REMAINING TASKS (Future Development)**
|
|
||||||
@ -1,254 +0,0 @@
|
|||||||
# Garage Web UI API Upgrade Report
|
|
||||||
|
|
||||||
## Upgrade Overview
|
|
||||||
|
|
||||||
The Garage Web UI project has been successfully upgraded from Garage Admin API v1 to v2, with all linting issues resolved and API endpoints aligned with the official specification.
|
|
||||||
|
|
||||||
**⚠️ Implementation Note**: This project now fully aligns with the official Garage Admin API v2 specification. For the authoritative API specification, please refer to [https://garagehq.deuxfleurs.fr/api/garage-admin-v2.html](https://garagehq.deuxfleurs.fr/api/garage-admin-v2.html).
|
|
||||||
|
|
||||||
## Upgrade Timeline
|
|
||||||
|
|
||||||
- **Completion Date**: July 2025
|
|
||||||
- **Current Version**: v1.0.9
|
|
||||||
- **Scope of Upgrade**: All API calls within the frontend React hooks
|
|
||||||
- **Code Quality**: All ESLint errors and warnings resolved
|
|
||||||
- **API Alignment**: Fully aligned with official Garage Admin API v2 specification
|
|
||||||
|
|
||||||
## Upgrade Details
|
|
||||||
|
|
||||||
### 1. Home Page (`src/pages/home/hooks.ts`)
|
|
||||||
|
|
||||||
- ✅ `useNodesHealth`: `/v1/health` → `/v2/GetClusterHealth`
|
|
||||||
|
|
||||||
### 2. Cluster Page (`src/pages/cluster/hooks.ts`)
|
|
||||||
|
|
||||||
- ✅ `useClusterStatus`: `/v1/status` → `/v2/GetClusterStatus`
|
|
||||||
- ✅ `useClusterLayout`: `/v1/layout` → `/v2/GetClusterLayout`
|
|
||||||
- ✅ `useConnectNode`: `/v1/connect` → `/v2/ConnectClusterNodes`
|
|
||||||
- ✅ `useAssignNode`: `/v1/layout` → `/v2/UpdateClusterLayout`
|
|
||||||
- ✅ `useUnassignNode`: `/v1/layout` → `/v2/UpdateClusterLayout`
|
|
||||||
- ✅ `useRevertChanges`: `/v1/layout/revert` → `/v2/RevertClusterLayout`
|
|
||||||
- ✅ `useApplyChanges`: `/v1/layout/apply` → `/v2/ApplyClusterLayout`
|
|
||||||
|
|
||||||
### 3. Keys Page (`src/pages/keys/hooks.ts`)
|
|
||||||
|
|
||||||
- ✅ `useKeys`: `/v1/key?list` → `/v2/ListKeys`
|
|
||||||
- ✅ `useCreateKey`: `/v1/key` → `/v2/CreateKey`
|
|
||||||
- ✅ `useCreateKey` (Import): `/v1/key/import` → `/v2/ImportKey`
|
|
||||||
- ✅ `useRemoveKey`: `/v1/key` → `/v2/DeleteKey?id={id}` (POST method, aligned with official spec)
|
|
||||||
|
|
||||||
### 4. Buckets Page (`src/pages/buckets/hooks.ts`)
|
|
||||||
|
|
||||||
- ✅ `useBuckets`: Custom `/buckets` endpoint → `/v2/ListBuckets` (enhanced with bucket details)
|
|
||||||
- ✅ `useCreateBucket`: `/v1/bucket` → `/v2/CreateBucket`
|
|
||||||
|
|
||||||
### 5. Bucket Management Page (`src/pages/buckets/manage/hooks.ts`)
|
|
||||||
|
|
||||||
- ✅ `useBucket`: `/v1/bucket` → `/v2/GetBucketInfo`
|
|
||||||
- ✅ `useUpdateBucket`: `/v1/bucket` → `/v2/UpdateBucket` (POST method)
|
|
||||||
- ✅ `useAddAlias`: `/v1/bucket/alias/global` → `/v2/AddBucketAlias` (POST method)
|
|
||||||
- ✅ `useRemoveAlias`: `/v1/bucket/alias/global` → `/v2/RemoveBucketAlias` (POST method)
|
|
||||||
- ✅ `useAllowKey`: `/v1/bucket/allow` → `/v2/AllowBucketKey`
|
|
||||||
- ✅ `useDenyKey`: `/v1/bucket/deny` → `/v2/DenyBucketKey`
|
|
||||||
- ✅ `useRemoveBucket`: `/v1/bucket` → `/v2/DeleteBucket?id={id}` (POST method, aligned with official spec)
|
|
||||||
|
|
||||||
### 6. Object Browser (`src/pages/buckets/manage/browse/hooks.ts`)
|
|
||||||
|
|
||||||
- ✅ `useBrowseObjects`: New custom `/browse/{bucket}` endpoint for S3-compatible object browsing
|
|
||||||
- ✅ `usePutObject`: New custom `/browse/{bucket}/{key}` endpoint for file uploads
|
|
||||||
- ✅ `useDeleteObject`: New custom `/browse/{bucket}/{key}` endpoint for file/folder deletion
|
|
||||||
|
|
||||||
### 7. Authentication (`src/pages/auth/hooks.ts` and `src/hooks/useAuth.ts`)
|
|
||||||
|
|
||||||
- ✅ `useLogin`: New custom `/auth/login` endpoint
|
|
||||||
- ✅ `useAuth`: New custom `/auth/status` endpoint for session management
|
|
||||||
|
|
||||||
### 8. Configuration (`src/hooks/useConfig.ts`)
|
|
||||||
|
|
||||||
- ✅ `useConfig`: New custom `/config` endpoint for garage configuration access
|
|
||||||
|
|
||||||
## Upgrade Statistics
|
|
||||||
|
|
||||||
### API Endpoint Mapping
|
|
||||||
|
|
||||||
| Original v1 Endpoint | Official v2 Endpoint | Implementation | Status |
|
|
||||||
| -------------------------------------------- | ---------------------------------- | ----------- | ------ |
|
|
||||||
| `/v1/health` | `GET /v2/GetClusterHealth` | `GET /v2/GetClusterHealth` | ✅ |
|
|
||||||
| `/v1/status` | `GET /v2/GetClusterStatus` | `GET /v2/GetClusterStatus` | ✅ |
|
|
||||||
| `/v1/layout` | `GET /v2/GetClusterLayout` | `GET /v2/GetClusterLayout` | ✅ |
|
|
||||||
| `/v1/connect` | `POST /v2/ConnectClusterNodes` | `POST /v2/ConnectClusterNodes` | ✅ |
|
|
||||||
| `/v1/layout` (POST) | `POST /v2/UpdateClusterLayout` | `POST /v2/UpdateClusterLayout` | ✅ |
|
|
||||||
| `/v1/layout/revert` | `POST /v2/RevertClusterLayout` | `POST /v2/RevertClusterLayout` | ✅ |
|
|
||||||
| `/v1/layout/apply` | `POST /v2/ApplyClusterLayout` | `POST /v2/ApplyClusterLayout` | ✅ |
|
|
||||||
| `/v1/key?list` | `GET /v2/ListKeys` | `GET /v2/ListKeys` | ✅ |
|
|
||||||
| `/v1/key` (POST) | `POST /v2/CreateKey` | `POST /v2/CreateKey` | ✅ |
|
|
||||||
| `/v1/key/import` | `POST /v2/ImportKey` | `POST /v2/ImportKey` | ✅ |
|
|
||||||
| `/v1/key` (DELETE) | `POST /v2/DeleteKey?id={id}` | `POST /v2/DeleteKey?id={id}` | ✅ |
|
|
||||||
| `/buckets` | `GET /v2/ListBuckets` | `GET /v2/ListBuckets` | ✅ |
|
|
||||||
| `/v1/bucket` (POST) | `POST /v2/CreateBucket` | `POST /v2/CreateBucket` | ✅ |
|
|
||||||
| `/v1/bucket` (GET) | `GET /v2/GetBucketInfo` | `GET /v2/GetBucketInfo` | ✅ |
|
|
||||||
| `/v1/bucket` (PUT) | `POST /v2/UpdateBucket` | `POST /v2/UpdateBucket` | ✅ |
|
|
||||||
| `/v1/bucket` (DELETE) | `POST /v2/DeleteBucket?id={id}` | `POST /v2/DeleteBucket?id={id}` | ✅ |
|
|
||||||
| `/v1/bucket/alias/global` (PUT) | `POST /v2/AddBucketAlias` | `POST /v2/AddBucketAlias` | ✅ |
|
|
||||||
| `/v1/bucket/alias/global` (DELETE) | `POST /v2/RemoveBucketAlias` | `POST /v2/RemoveBucketAlias` | ✅ |
|
|
||||||
| `/v1/bucket/allow` | `POST /v2/AllowBucketKey` | `POST /v2/AllowBucketKey` | ✅ |
|
|
||||||
| `/v1/bucket/deny` | `POST /v2/DenyBucketKey` | `POST /v2/DenyBucketKey` | ✅ |
|
|
||||||
|
|
||||||
**Note**: "Official" refers to the Garage Admin API v2 specification, "Impl" refers to the Garage Web UI implementation which may use more REST-compliant HTTP methods.
|
|
||||||
|
|
||||||
### Custom Backend Endpoints
|
|
||||||
|
|
||||||
In addition to the standard Garage Admin API v2 endpoints, the Garage Web UI implements several custom backend endpoints for enhanced functionality:
|
|
||||||
|
|
||||||
| Endpoint | HTTP Method | Purpose | Status |
|
|
||||||
| -------- | ----------- | ------- | ------ |
|
|
||||||
| `/config` | GET | Get garage configuration | ✅ |
|
|
||||||
| `/auth/login` | POST | User authentication | ✅ |
|
|
||||||
| `/auth/logout` | POST | User logout | ✅ |
|
|
||||||
| `/auth/status` | GET | Authentication status | ✅ |
|
|
||||||
| `/buckets` | GET | Enhanced bucket listing with details | ✅ |
|
|
||||||
| `/browse/{bucket}` | GET | Browse bucket objects | ✅ |
|
|
||||||
| `/browse/{bucket}/{key...}` | GET | View/download object | ✅ |
|
|
||||||
| `/browse/{bucket}/{key...}` | PUT | Upload object | ✅ |
|
|
||||||
| `/browse/{bucket}/{key...}` | DELETE | Delete object/folder | ✅ |
|
|
||||||
|
|
||||||
### Upgrade Count
|
|
||||||
|
|
||||||
- **Total Standard v2 Endpoints Implemented**: 18
|
|
||||||
- **Custom Backend Endpoints**: 9
|
|
||||||
- **Total API Endpoints**: 27
|
|
||||||
- **Successfully Upgraded**: 18 (100% of planned v1→v2 migrations)
|
|
||||||
- **Custom Features Added**: 9 (Object browsing, authentication, enhanced bucket listing)
|
|
||||||
- **Number of Files Upgraded**: 5 TypeScript hook files + 1 backend router
|
|
||||||
|
|
||||||
## Backend Compatibility
|
|
||||||
|
|
||||||
✅ **No Backend Modifications Required**:
|
|
||||||
|
|
||||||
- The backend uses a reverse proxy (`ProxyHandler`) to directly forward API requests to the Garage Admin API.
|
|
||||||
- All v2 API requests are automatically forwarded to the correct Garage Admin endpoints.
|
|
||||||
- No changes to the Go backend code were necessary.
|
|
||||||
|
|
||||||
## Build Verification
|
|
||||||
|
|
||||||
✅ **Build Successful**:
|
|
||||||
|
|
||||||
- TypeScript compilation passed.
|
|
||||||
- Vite bundling was successful.
|
|
||||||
- No compilation errors.
|
|
||||||
- Docker build working properly.
|
|
||||||
|
|
||||||
✅ **Code Quality**:
|
|
||||||
|
|
||||||
- All ESLint errors and warnings have been resolved.
|
|
||||||
- Type definitions have been optimized (removed all `any` types).
|
|
||||||
- All React hooks follow proper dependency rules.
|
|
||||||
- Form controls are properly managed (controlled vs uncontrolled).
|
|
||||||
- All components have proper TypeScript interfaces.
|
|
||||||
- React component keys are properly assigned for list items.
|
|
||||||
- Input fields have appropriate `readOnly` props where needed.
|
|
||||||
|
|
||||||
## New Feature Availability
|
|
||||||
|
|
||||||
After upgrading to the v2 API, the project now utilizes the following enhanced features:
|
|
||||||
|
|
||||||
### Enhanced Cluster Management
|
|
||||||
|
|
||||||
- More detailed cluster health status information via `/v2/GetClusterHealth`
|
|
||||||
- Improved layout management operations with `/v2/UpdateClusterLayout`
|
|
||||||
- Better node connection handling through `/v2/ConnectClusterNodes`
|
|
||||||
|
|
||||||
### Enhanced Key Management
|
|
||||||
|
|
||||||
- Support for more key types through `/v2/CreateKey`
|
|
||||||
- Improved permission management with `/v2/AllowBucketKey` and `/v2/DenyBucketKey`
|
|
||||||
- Better key import functionality via `/v2/ImportKey`
|
|
||||||
|
|
||||||
### Enhanced Bucket Management
|
|
||||||
|
|
||||||
- Richer bucket metadata from `/v2/GetBucketInfo`
|
|
||||||
- Improved alias management with `/v2/AddBucketAlias` and `/v2/RemoveBucketAlias`
|
|
||||||
- Finer-grained permission control through updated permission APIs
|
|
||||||
|
|
||||||
## Recent Improvements & Fixes
|
|
||||||
|
|
||||||
### ✅ **API Endpoint Corrections (July 2025)**
|
|
||||||
|
|
||||||
1. **Bucket Alias Operations**:
|
|
||||||
- Fixed `AddBucketAlias`: Now uses correct endpoint `/v2/AddBucketAlias` with POST method
|
|
||||||
- Fixed `RemoveBucketAlias`: Now uses correct endpoint `/v2/RemoveBucketAlias` with POST method
|
|
||||||
- Updated request format to use `{ bucketId, globalAlias }` in request body
|
|
||||||
|
|
||||||
2. **Delete Operations**:
|
|
||||||
- Fixed `DeleteKey`: Now uses `POST /v2/DeleteKey?id={id}` (aligned with official spec)
|
|
||||||
- Fixed `DeleteBucket`: Now uses `POST /v2/DeleteBucket?id={id}` (aligned with official spec)
|
|
||||||
|
|
||||||
### ✅ **Code Quality Improvements (July 2025)**
|
|
||||||
|
|
||||||
1. **TypeScript & ESLint Fixes**:
|
|
||||||
- Removed all `any` types in favor of proper TypeScript interfaces
|
|
||||||
- Fixed all React Hook dependency warnings
|
|
||||||
- Resolved controlled vs uncontrolled input warnings
|
|
||||||
- Added proper `key` props to list items
|
|
||||||
- Added `readOnly` props to display-only input fields
|
|
||||||
|
|
||||||
2. **Component Fixes**:
|
|
||||||
- **Chips Component**: Fixed TypeScript prop spreading
|
|
||||||
- **Select Component**: Improved ref handling
|
|
||||||
- **Disclosure Hooks**: Enhanced type safety
|
|
||||||
- **Page Context**: Fixed infinite loop issues with proper memoization
|
|
||||||
- **Main Layout**: Fixed sidebar toggle on mobile devices
|
|
||||||
- **ShareDialog**: Added `readOnly` prop to URL input field
|
|
||||||
- **Permissions Tab**: Added proper keys and readOnly checkboxes
|
|
||||||
- **Create Key Dialog**: Fixed uncontrolled to controlled input warnings
|
|
||||||
|
|
||||||
3. **Mobile & UX Improvements**:
|
|
||||||
- Fixed sidebar functionality on mobile devices
|
|
||||||
- Resolved burger menu toggle issues
|
|
||||||
- Improved form validation and error handling
|
|
||||||
|
|
||||||
## Production Status
|
|
||||||
|
|
||||||
✅ **Production Ready**:
|
|
||||||
|
|
||||||
1. ✅ **Type Definition Optimization**: All `any` types have been replaced with specific interface definitions.
|
|
||||||
2. ✅ **Functional Testing**: All upgraded features tested and working in production.
|
|
||||||
3. ✅ **Documentation Update**: Project documentation updated to reflect the use of the v2 API.
|
|
||||||
4. ✅ **Error Handling**: Error handling logic adjusted for the v2 API's response format.
|
|
||||||
|
|
||||||
## Future Enhancement Opportunities
|
|
||||||
|
|
||||||
1. **Additional v2 Features**: Implement newly available v2 API features such as:
|
|
||||||
- Admin token management (`/v2/CreateAdminToken`, `/v2/ListAdminTokens`)
|
|
||||||
- Enhanced node monitoring (`/v2/GetNodeInfo`, `/v2/GetNodeStatistics`)
|
|
||||||
- Block management and repair tools (`/v2/GetBlockInfo`, `/v2/LaunchRepairOperation`)
|
|
||||||
2. **User Experience**: Continue improving the UI for mobile devices and add real-time updates.
|
|
||||||
3. **Monitoring Integration**: Enhanced Prometheus metrics visualization.
|
|
||||||
4. **Bulk Operations**: Support for bulk management of buckets and access keys.
|
|
||||||
|
|
||||||
## Risk Assessment
|
|
||||||
|
|
||||||
### ✅ Production Stable
|
|
||||||
|
|
||||||
- API path upgrade completed successfully.
|
|
||||||
- No compilation errors.
|
|
||||||
- Excellent backend compatibility.
|
|
||||||
- All features tested and working.
|
|
||||||
|
|
||||||
### ✅ Features Fully Operational
|
|
||||||
|
|
||||||
- All upgraded API endpoints working correctly.
|
|
||||||
- Error response handling optimized.
|
|
||||||
- API parameter formats fully compatible.
|
|
||||||
|
|
||||||
## Rollback Plan
|
|
||||||
|
|
||||||
To roll back to the v1 API if necessary:
|
|
||||||
|
|
||||||
1. Restore the API paths in all hook files.
|
|
||||||
2. Ensure the Garage server supports the v1 API.
|
|
||||||
3. Recompile and redeploy.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**Upgrade Complete**: The Garage Web UI has been successfully upgraded to Garage Admin API v2 and is currently running in production with enhanced functionality and better performance.
|
|
||||||
@ -1,523 +0,0 @@
|
|||||||
# Garage Admin API Documentation
|
|
||||||
|
|
||||||
## Important Note
|
|
||||||
|
|
||||||
This document reflects the Garage Web UI's implementation of the [Garage Admin API v2](https://garagehq.deuxfleurs.fr/api/garage-admin-v2.html).
|
|
||||||
|
|
||||||
**✅ Full Alignment**: As of July 2025, this implementation is fully aligned with the official Garage Admin API v2 specification. All HTTP methods, request formats, and response handling match the official documentation.
|
|
||||||
|
|
||||||
- **Official HTML Documentation**: [https://garagehq.deuxfleurs.fr/api/garage-admin-v2.html](https://garagehq.deuxfleurs.fr/api/garage-admin-v2.html)
|
|
||||||
- **Official JSON Specification**: [https://garagehq.deuxfleurs.fr/api/garage-admin-v2.json](https://garagehq.deuxfleurs.fr/api/garage-admin-v2.json)
|
|
||||||
|
|
||||||
## Overview
|
|
||||||
|
|
||||||
The Garage Administration API is a REST API for programmatically managing a Garage cluster, providing complete functionality for cluster management, bucket management, access control, and more. The current version is v2, and the base API address is typically `http://localhost:3903`.
|
|
||||||
|
|
||||||
**⚠️ Important Note**: This documentation reflects the implementation used by the Garage Web UI project. For the most accurate and up-to-date API specifications, please refer to the official documentation at:
|
|
||||||
- **HTML Documentation**: [https://garagehq.deuxfleurs.fr/api/garage-admin-v2.html](https://garagehq.deuxfleurs.fr/api/garage-admin-v2.html)
|
|
||||||
- **JSON Specification**: [https://garagehq.deuxfleurs.fr/api/garage-admin-v2.json](https://garagehq.deuxfleurs.fr/api/garage-admin-v2.json)
|
|
||||||
|
|
||||||
## Current Implementation Status
|
|
||||||
|
|
||||||
**✅ Production Ready & Fully Compliant**: The Garage Web UI implements Garage Admin API v2 with full compliance to the official specification.
|
|
||||||
|
|
||||||
## Implementation Details
|
|
||||||
|
|
||||||
The Garage Web UI utilizes both standard Garage Admin API v2 endpoints and custom backend endpoints:
|
|
||||||
|
|
||||||
### **Standard Garage Admin API v2 Endpoints**
|
|
||||||
- **Status**: ✅ **18 endpoints implemented**
|
|
||||||
- **Compliance**: ✅ **Fully aligned with official specification**
|
|
||||||
- **HTTP Methods**: ✅ **Match official documentation exactly**
|
|
||||||
- **Request/Response Format**: ✅ **Compliant with official spec**
|
|
||||||
|
|
||||||
### **Custom Backend Extensions**
|
|
||||||
- **Status**: ✅ **9 custom endpoints implemented**
|
|
||||||
- **Purpose**: Enhanced functionality (authentication, object browsing, file management)
|
|
||||||
- **Integration**: Seamlessly integrated with standard API calls
|
|
||||||
|
|
||||||
## Authentication
|
|
||||||
|
|
||||||
### Bearer Token Authentication
|
|
||||||
|
|
||||||
All API requests must include authentication information in the HTTP header:
|
|
||||||
|
|
||||||
```http
|
|
||||||
Authorization: Bearer <token>
|
|
||||||
```
|
|
||||||
|
|
||||||
### Token Types
|
|
||||||
|
|
||||||
1. **User-defined Token** (Recommended)
|
|
||||||
|
|
||||||
- Can be dynamically created and managed
|
|
||||||
- Supports scope limitations
|
|
||||||
- Supports setting an expiration time
|
|
||||||
- Created using the `garage admin-token` command
|
|
||||||
|
|
||||||
2. **Master Token** (Deprecated)
|
|
||||||
- Specified in the configuration file
|
|
||||||
- `admin_token`: For admin endpoint access
|
|
||||||
- `metrics_token`: For metrics endpoint access
|
|
||||||
|
|
||||||
### Example of Creating a User-defined Token
|
|
||||||
|
|
||||||
```bash
|
|
||||||
garage admin-token create --expires-in 30d \
|
|
||||||
--scope ListBuckets,GetBucketInfo,ListKeys,GetKeyInfo,CreateBucket,CreateKey,AllowBucketKey,DenyBucketKey \
|
|
||||||
my-token
|
|
||||||
```
|
|
||||||
|
|
||||||
## API Endpoint Categories
|
|
||||||
|
|
||||||
### 1. Cluster Management
|
|
||||||
|
|
||||||
#### Get Cluster Health
|
|
||||||
|
|
||||||
- **Endpoint**: `GET /v2/GetClusterHealth`
|
|
||||||
- **Description**: Returns the global status of the cluster, including the number of connected nodes, healthy storage nodes, partition status, etc.
|
|
||||||
- **Response Example**:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"status": "healthy",
|
|
||||||
"knownNodes": 3,
|
|
||||||
"connectedNodes": 3,
|
|
||||||
"storageNodes": 3,
|
|
||||||
"storageNodesOk": 3,
|
|
||||||
"partitions": 256,
|
|
||||||
"partitionsQuorum": 256,
|
|
||||||
"partitionsAllOk": 256
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Get Cluster Status
|
|
||||||
|
|
||||||
- **Endpoint**: `GET /v2/GetClusterStatus`
|
|
||||||
- **Description**: Returns detailed cluster status information, including node information and layout configuration.
|
|
||||||
|
|
||||||
#### Get Cluster Statistics
|
|
||||||
|
|
||||||
- **Endpoint**: `GET /v2/GetClusterStatistics`
|
|
||||||
- **Description**: Gets cluster-level statistics.
|
|
||||||
|
|
||||||
#### Connect Cluster Nodes
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/ConnectClusterNodes`
|
|
||||||
- **Description**: Instructs the current node to connect to other Garage nodes.
|
|
||||||
- **Request Body**: An array of node addresses `["<node_id>@<net_address>"]`
|
|
||||||
|
|
||||||
### 2. Cluster Layout Management
|
|
||||||
|
|
||||||
#### Get Cluster Layout
|
|
||||||
|
|
||||||
- **Endpoint**: `GET /v2/GetClusterLayout`
|
|
||||||
- **Description**: Returns the current cluster layout configuration and pending changes.
|
|
||||||
|
|
||||||
#### Update Cluster Layout
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/UpdateClusterLayout`
|
|
||||||
- **Description**: Submits cluster layout changes to the staging area.
|
|
||||||
- **Request Body Example**:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"roles": [
|
|
||||||
{
|
|
||||||
"id": "node-id",
|
|
||||||
"zone": "zone1",
|
|
||||||
"capacity": 100000000000,
|
|
||||||
"tags": ["tag1", "tag2"]
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Apply Layout Changes
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/ApplyClusterLayout`
|
|
||||||
- **Description**: Applies staged layout changes to the cluster.
|
|
||||||
- **Request Body**: `{"version": <layout_version>}`
|
|
||||||
|
|
||||||
#### Preview Layout Changes
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/PreviewClusterLayoutChanges`
|
|
||||||
- **Description**: Previews the impact of layout changes without actually applying them.
|
|
||||||
|
|
||||||
#### Revert Layout Changes
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/RevertClusterLayout`
|
|
||||||
- **Description**: Clears all staged layout changes.
|
|
||||||
|
|
||||||
#### Get Layout History
|
|
||||||
|
|
||||||
- **Endpoint**: `GET /v2/GetClusterLayoutHistory`
|
|
||||||
- **Description**: Gets the history of cluster layout versions.
|
|
||||||
|
|
||||||
### 3. Bucket Management
|
|
||||||
|
|
||||||
#### List All Buckets
|
|
||||||
|
|
||||||
- **Endpoint**: `GET /v2/ListBuckets`
|
|
||||||
- **Description**: Returns all buckets and their aliases in the cluster.
|
|
||||||
|
|
||||||
#### Get Bucket Information
|
|
||||||
|
|
||||||
- **Endpoint**: `GET /v2/GetBucketInfo`
|
|
||||||
- **Parameters**:
|
|
||||||
- `id`: Bucket ID
|
|
||||||
- `globalAlias`: Global alias
|
|
||||||
- `search`: Search pattern
|
|
||||||
- **Description**: Gets detailed bucket information, including permissions, statistics, quotas, etc.
|
|
||||||
|
|
||||||
#### Create Bucket
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/CreateBucket`
|
|
||||||
- **Request Body Example**:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"globalAlias": "my-bucket",
|
|
||||||
"localAlias": {
|
|
||||||
"accessKeyId": "key-id",
|
|
||||||
"alias": "local-name",
|
|
||||||
"allow": {
|
|
||||||
"read": true,
|
|
||||||
"write": true,
|
|
||||||
"owner": false
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Update Bucket
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/UpdateBucket/{id}`
|
|
||||||
- **Description**: Updates a bucket's website configuration and quota settings.
|
|
||||||
- **Request Body Example**:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"websiteAccess": {
|
|
||||||
"enabled": true,
|
|
||||||
"indexDocument": "index.html",
|
|
||||||
"errorDocument": "error.html"
|
|
||||||
},
|
|
||||||
"quotas": {
|
|
||||||
"maxSize": 1000000000,
|
|
||||||
"maxObjects": 10000
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Delete Bucket
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/DeleteBucket?id={id}` (Aligned with Official Specification)
|
|
||||||
- **Method**: POST with query parameter
|
|
||||||
- **Purpose**: Delete a bucket
|
|
||||||
- **Parameters**: Bucket ID in query parameter
|
|
||||||
|
|
||||||
#### Cleanup Incomplete Uploads
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/CleanupIncompleteUploads`
|
|
||||||
- **Request Body**: `{"bucketId": "bucket-id", "olderThanSecs": 86400}`
|
|
||||||
|
|
||||||
#### Inspect Object
|
|
||||||
|
|
||||||
- **Endpoint**: `GET /v2/InspectObject`
|
|
||||||
- **Parameters**: `bucketId`, `key`
|
|
||||||
- **Description**: Gets detailed internal status information for an object.
|
|
||||||
|
|
||||||
### 4. Bucket Alias Management
|
|
||||||
|
|
||||||
#### Add Bucket Alias
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/AddBucketAlias`
|
|
||||||
- **Description**: Adds a global or local alias for a bucket.
|
|
||||||
|
|
||||||
#### Remove Bucket Alias
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/RemoveBucketAlias`
|
|
||||||
- **Description**: Removes a bucket's alias.
|
|
||||||
|
|
||||||
### 5. Access Key Management
|
|
||||||
|
|
||||||
#### List Access Keys
|
|
||||||
|
|
||||||
- **Endpoint**: `GET /v2/ListKeys`
|
|
||||||
- **Description**: Returns all API access keys.
|
|
||||||
|
|
||||||
#### Get Key Information
|
|
||||||
|
|
||||||
- **Endpoint**: `GET /v2/GetKeyInfo`
|
|
||||||
- **Parameters**:
|
|
||||||
- `id`: Key ID
|
|
||||||
- `search`: Search pattern
|
|
||||||
- `showSecretKey`: Whether to return the secret key (default is false).
|
|
||||||
|
|
||||||
#### Create Access Key
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/CreateKey`
|
|
||||||
- **Request Body Example**:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"name": "my-key",
|
|
||||||
"allow": {
|
|
||||||
"createBucket": true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Update Access Key
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/UpdateKey/{id}`
|
|
||||||
- **Description**: Updates a key's name, permissions, and expiration time.
|
|
||||||
|
|
||||||
#### Delete Access Key
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/DeleteKey?id={id}` (Aligned with Official Specification)
|
|
||||||
- **Method**: POST with query parameter
|
|
||||||
- **Purpose**: Delete an access key
|
|
||||||
- **Parameters**: Key ID in query parameter
|
|
||||||
|
|
||||||
#### Import Access Key
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/ImportKey`
|
|
||||||
- **Description**: Imports an existing access key (only for migration and backup recovery).
|
|
||||||
|
|
||||||
### 6. Permission Management
|
|
||||||
|
|
||||||
#### Grant Permission
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/AllowBucketKey`
|
|
||||||
- **Description**: Grants a key permission to perform operations on a bucket.
|
|
||||||
- **Request Body Example**:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"bucketId": "bucket-id",
|
|
||||||
"accessKeyId": "key-id",
|
|
||||||
"permissions": {
|
|
||||||
"read": true,
|
|
||||||
"write": true,
|
|
||||||
"owner": false
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Deny Permission
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/DenyBucketKey`
|
|
||||||
- **Description**: Removes a key's permission to perform operations on a bucket.
|
|
||||||
|
|
||||||
### 7. Admin API Token Management
|
|
||||||
|
|
||||||
#### List Admin Tokens
|
|
||||||
|
|
||||||
- **Endpoint**: `GET /v2/ListAdminTokens`
|
|
||||||
|
|
||||||
#### Get Token Information
|
|
||||||
|
|
||||||
- **Endpoint**: `GET /v2/GetAdminTokenInfo`
|
|
||||||
- **Parameters**: `id` or `search`
|
|
||||||
|
|
||||||
#### Get Current Token Information
|
|
||||||
|
|
||||||
- **Endpoint**: `GET /v2/GetCurrentAdminTokenInfo`
|
|
||||||
|
|
||||||
#### Create Admin Token
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/CreateAdminToken`
|
|
||||||
- **Request Body Example**:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"name": "my-admin-token",
|
|
||||||
"expiration": "2025-12-31T23:59:59Z",
|
|
||||||
"scope": ["ListBuckets", "GetBucketInfo", "CreateBucket"]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Update Admin Token
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/UpdateAdminToken/{id}`
|
|
||||||
|
|
||||||
#### Delete Admin Token
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/DeleteAdminToken/{id}`
|
|
||||||
|
|
||||||
### 8. Node Management
|
|
||||||
|
|
||||||
#### Get Node Information
|
|
||||||
|
|
||||||
- **Endpoint**: `GET /v2/GetNodeInfo/{node}`
|
|
||||||
- **Parameters**: `node` - Node ID, `*` (all nodes), or `self` (current node)
|
|
||||||
|
|
||||||
#### Get Node Statistics
|
|
||||||
|
|
||||||
- **Endpoint**: `GET /v2/GetNodeStatistics/{node}`
|
|
||||||
|
|
||||||
#### Create Metadata Snapshot
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/CreateMetadataSnapshot/{node}`
|
|
||||||
|
|
||||||
#### Launch Repair Operation
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/LaunchRepairOperation/{node}`
|
|
||||||
- **Repair Types**: `tables`, `blocks`, `versions`, `multipartUploads`, `blockRefs`, `blockRc`, `rebalance`, `aliases`
|
|
||||||
|
|
||||||
### 9. Worker Process Management
|
|
||||||
|
|
||||||
#### List Workers
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/ListWorkers/{node}`
|
|
||||||
|
|
||||||
#### Get Worker Information
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/GetWorkerInfo/{node}`
|
|
||||||
|
|
||||||
#### Get Worker Variable
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/GetWorkerVariable/{node}`
|
|
||||||
|
|
||||||
#### Set Worker Variable
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/SetWorkerVariable/{node}`
|
|
||||||
|
|
||||||
### 10. Block Management
|
|
||||||
|
|
||||||
#### Get Block Information
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/GetBlockInfo/{node}`
|
|
||||||
- **Request Body**: `{"blockHash": "hash-value"}`
|
|
||||||
|
|
||||||
#### List Block Errors
|
|
||||||
|
|
||||||
- **Endpoint**: `GET /v2/ListBlockErrors/{node}`
|
|
||||||
|
|
||||||
#### Retry Block Resync
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/RetryBlockResync/{node}`
|
|
||||||
|
|
||||||
#### Purge Blocks
|
|
||||||
|
|
||||||
- **Endpoint**: `POST /v2/PurgeBlocks/{node}`
|
|
||||||
- **Warning**: This operation permanently deletes all objects that reference these blocks.
|
|
||||||
|
|
||||||
### 11. Special Endpoints
|
|
||||||
|
|
||||||
#### Health Check
|
|
||||||
|
|
||||||
- **Endpoint**: `GET /health`
|
|
||||||
- **Authentication**: None required
|
|
||||||
- **Description**: Quick health check, returns 200 if the service is available.
|
|
||||||
|
|
||||||
#### Prometheus Metrics
|
|
||||||
|
|
||||||
- **Endpoint**: `GET /metrics`
|
|
||||||
- **Authentication**: Optional (using `metrics_token`)
|
|
||||||
- **Description**: Returns monitoring metrics in Prometheus format.
|
|
||||||
|
|
||||||
#### On-Demand TLS Check
|
|
||||||
|
|
||||||
- **Endpoint**: `GET /check?domain=<domain>`
|
|
||||||
- **Authentication**: None required
|
|
||||||
- **Description**: Used for on-demand TLS certificate validation by reverse proxies (like Caddy).
|
|
||||||
|
|
||||||
## Usage Example
|
|
||||||
|
|
||||||
### Using curl
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Get cluster health status
|
|
||||||
curl -H 'Authorization: Bearer YOUR_TOKEN' \
|
|
||||||
http://localhost:3903/v2/GetClusterHealth
|
|
||||||
|
|
||||||
# Create a bucket
|
|
||||||
curl -X POST \
|
|
||||||
-H 'Authorization: Bearer YOUR_TOKEN' \
|
|
||||||
-H 'Content-Type: application/json' \
|
|
||||||
-d '{"globalAlias": "my-bucket"}' \
|
|
||||||
http://localhost:3903/v2/CreateBucket
|
|
||||||
|
|
||||||
# List all buckets
|
|
||||||
curl -H 'Authorization: Bearer YOUR_TOKEN' \
|
|
||||||
http://localhost:3903/v2/ListBuckets
|
|
||||||
```
|
|
||||||
|
|
||||||
### Using the Garage CLI
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Call via internal RPC (no authentication required)
|
|
||||||
garage json-api GetClusterHealth
|
|
||||||
|
|
||||||
# Call with parameters
|
|
||||||
garage json-api GetBucketInfo '{"globalAlias": "my-bucket"}'
|
|
||||||
|
|
||||||
# Read parameters from standard input
|
|
||||||
garage json-api CreateBucket -
|
|
||||||
{"globalAlias": "test-bucket"}
|
|
||||||
<EOF>
|
|
||||||
```
|
|
||||||
|
|
||||||
## Error Handling
|
|
||||||
|
|
||||||
The API uses standard HTTP status codes:
|
|
||||||
|
|
||||||
- `200 OK` - Request successful
|
|
||||||
- `400 Bad Request` - Invalid request parameters
|
|
||||||
- `401 Unauthorized` - Authentication failed
|
|
||||||
- `403 Forbidden` - Insufficient permissions
|
|
||||||
- `404 Not Found` - Resource not found
|
|
||||||
- `500 Internal Server Error` - Internal server error
|
|
||||||
|
|
||||||
Error responses typically include detailed error information:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"error": "Bucket not found",
|
|
||||||
"code": "BucketNotFound"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Permission Scopes
|
|
||||||
|
|
||||||
Admin tokens can be restricted to specific API endpoints:
|
|
||||||
|
|
||||||
- `*` - Allows all endpoints
|
|
||||||
- `ListBuckets` - List buckets
|
|
||||||
- `GetBucketInfo` - Get bucket information
|
|
||||||
- `CreateBucket` - Create a bucket
|
|
||||||
- `ListKeys` - List access keys
|
|
||||||
- `CreateKey` - Create an access key
|
|
||||||
- `AllowBucketKey` - Grant permissions
|
|
||||||
- `DenyBucketKey` - Deny permissions
|
|
||||||
- `Metrics` - Access the metrics endpoint
|
|
||||||
|
|
||||||
## Best Practices
|
|
||||||
|
|
||||||
1. **Use User-defined Tokens**: Avoid using the master token from the configuration file.
|
|
||||||
2. **Set Appropriate Scopes**: Grant only necessary permissions.
|
|
||||||
3. **Set Expiration Times**: Rotate tokens periodically.
|
|
||||||
4. **Monitor API Usage**: Monitor API calls via the `/metrics` endpoint.
|
|
||||||
5. **Handle Errors**: Properly handle various error conditions.
|
|
||||||
6. **Bulk Operations**: For a large number of operations, consider using bulk APIs or scripts.
|
|
||||||
|
|
||||||
## Version History
|
|
||||||
|
|
||||||
- **v0** - First introduced in Garage v0.7.2 (deprecated)
|
|
||||||
- **v1** - Introduced in Garage v0.9.0 (deprecated, still supported for backward compatibility)
|
|
||||||
- **v2** - Introduced in Garage v2.0.0 (current version, actively used by Garage Web UI)
|
|
||||||
|
|
||||||
**Migration Notes**:
|
|
||||||
- The Garage Web UI has successfully migrated from v1 to v2 API
|
|
||||||
- All core functionality now utilizes v2 endpoints for improved performance and feature access
|
|
||||||
- Legacy v1 endpoints remain available for backward compatibility but are not recommended for new implementations
|
|
||||||
|
|
||||||
## Related Links
|
|
||||||
|
|
||||||
- [Garage Official Documentation](https://garagehq.deuxfleurs.fr/documentation/)
|
|
||||||
- [OpenAPI Specification (HTML)](https://garagehq.deuxfleurs.fr/api/garage-admin-v2.html)
|
|
||||||
- [OpenAPI Specification (JSON)](https://garagehq.deuxfleurs.fr/api/garage-admin-v2.json)
|
|
||||||
- [Garage Source Code](https://git.deuxfleurs.fr/Deuxfleurs/garage)
|
|
||||||
@ -1,588 +0,0 @@
|
|||||||
# Garage Web UI Project Management Documentation
|
|
||||||
|
|
||||||
## Project Overview
|
|
||||||
|
|
||||||
**Garage Web UI** is a modern web management interface for the [Garage](https://garagehq.deuxfleurs.fr/) distributed object storage service. This project provides a clean, intuitive graphical interface to manage Garage clusters, serving as an important supplement to the official Garage command-line tools.
|
|
||||||
|
|
||||||
### 🎯 Project Positioning
|
|
||||||
|
|
||||||
- **Target Users**: Garage cluster administrators and operations personnel
|
|
||||||
- **Core Value**: Simplify the daily management operations of Garage clusters
|
|
||||||
- **Technology Stack**: TypeScript + React (Frontend) + Go (Backend)
|
|
||||||
|
|
||||||
## Features
|
|
||||||
|
|
||||||
### 🏥 Cluster Monitoring and Management
|
|
||||||
|
|
||||||
#### 1. Health Status Monitoring
|
|
||||||
|
|
||||||
- **Real-time Cluster Status**: Displays the overall health of the cluster (Healthy/Degraded/Unavailable)
|
|
||||||
- **Node Monitoring**: Real-time monitoring of the number of known nodes, connected nodes, and storage node status
|
|
||||||
- **Partition Status**: Monitors the health and quorum status of data partitions
|
|
||||||
|
|
||||||
#### 2. Cluster Layout Management
|
|
||||||
|
|
||||||
- **Visual Layout**: Graphically displays the cluster node distribution and storage configuration
|
|
||||||
- **Node Configuration**: Manage node attributes such as zone, capacity, and tags
|
|
||||||
- **Layout Changes**: Supports staging, previewing, applying, and reverting layout changes
|
|
||||||
- **History**: View the history of cluster layout changes
|
|
||||||
|
|
||||||
### 🗄️ Bucket Management
|
|
||||||
|
|
||||||
#### 1. Bucket Operations
|
|
||||||
|
|
||||||
- **Bucket List**: Displays all buckets and their basic information
|
|
||||||
- **Bucket Details**: View detailed statistics, configuration, and permission information for a bucket
|
|
||||||
- **Bucket Creation**: Supports creating buckets with global and local aliases
|
|
||||||
- **Bucket Configuration**: Update bucket website configuration, quota settings, etc.
|
|
||||||
|
|
||||||
#### 2. Object Browser
|
|
||||||
|
|
||||||
- **File Browsing**: Built-in object browser that supports folder structure browsing
|
|
||||||
- **File Operations**: Upload, download, and delete object files
|
|
||||||
- **Sharing Functionality**: Generate temporary access links
|
|
||||||
- **Bulk Operations**: Supports bulk file management
|
|
||||||
|
|
||||||
### 🔑 Access Control Management
|
|
||||||
|
|
||||||
#### 1. Access Key Management
|
|
||||||
|
|
||||||
- **Key List**: Displays all API access keys
|
|
||||||
- **Key Creation**: Create new S3-compatible access keys
|
|
||||||
- **Permission Configuration**: Set global permissions for keys (e.g., creating buckets)
|
|
||||||
- **Expiration Management**: Set expiration times for keys
|
|
||||||
|
|
||||||
#### 2. Permission Assignment
|
|
||||||
|
|
||||||
- **Bucket Permissions**: Assign permissions to access keys for specific buckets
|
|
||||||
- **Permission Types**: Supports Read, Write, and Owner permission levels
|
|
||||||
- **Permission Revocation**: Flexible mechanism for granting and revoking permissions
|
|
||||||
|
|
||||||
## Technical Architecture
|
|
||||||
|
|
||||||
### 🏗️ Overall Architecture
|
|
||||||
|
|
||||||
```
|
|
||||||
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
|
||||||
│ Web Browser │───▶│ Garage Web UI │───▶│ Garage Cluster │
|
|
||||||
│ (Frontend UI) │ │ (Go Backend) │ │ (Admin API) │
|
|
||||||
└─────────────────┘ └──────────────────┘ └─────────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
### 📁 Project Structure
|
|
||||||
|
|
||||||
```
|
|
||||||
garage-webui/
|
|
||||||
├── src/ # React Frontend Source
|
|
||||||
│ ├── pages/ # Page Components
|
|
||||||
│ │ ├── home/ # Home Dashboard
|
|
||||||
│ │ ├── cluster/ # Cluster Management
|
|
||||||
│ │ ├── buckets/ # Bucket Management
|
|
||||||
│ │ └── keys/ # Access Key Management
|
|
||||||
│ ├── components/ # Reusable Components
|
|
||||||
│ ├── hooks/ # React Hooks
|
|
||||||
│ └── lib/ # Utility Libraries
|
|
||||||
├── backend/ # Go Backend Source
|
|
||||||
│ ├── main.go # Service Entrypoint
|
|
||||||
│ ├── router/ # API Routes
|
|
||||||
│ ├── utils/ # Utility Functions
|
|
||||||
│ └── schema/ # Data Structures
|
|
||||||
├── docs/ # Project Documentation
|
|
||||||
└── misc/ # Screenshots and other resources
|
|
||||||
```
|
|
||||||
|
|
||||||
### 🔌 Backend Service Architecture
|
|
||||||
|
|
||||||
#### Core Modules
|
|
||||||
|
|
||||||
1. **Configuration Management** (`utils/garage.go`)
|
|
||||||
|
|
||||||
- Automatically reads the Garage configuration file (`garage.toml`)
|
|
||||||
- Extracts admin API endpoints, authentication information, etc.
|
|
||||||
- Supports overriding configuration with environment variables
|
|
||||||
|
|
||||||
2. **API Proxy** (`router/`)
|
|
||||||
|
|
||||||
- Proxies frontend requests to the Garage Admin API
|
|
||||||
- Handles authentication and error translation
|
|
||||||
- Provides a unified RESTful interface
|
|
||||||
|
|
||||||
3. **Session Management** (`utils/session.go`)
|
|
||||||
|
|
||||||
- Supports user authentication (optional)
|
|
||||||
- Session state management
|
|
||||||
|
|
||||||
4. **Caching Mechanism** (`utils/cache.go`)
|
|
||||||
- Caches API responses
|
|
||||||
- Reduces request pressure on the Garage cluster
|
|
||||||
|
|
||||||
## Deployment Scenarios
|
|
||||||
|
|
||||||
### 🐳 Docker Deployment (Recommended)
|
|
||||||
|
|
||||||
#### 1. Deploying with a Garage Cluster
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
garage:
|
|
||||||
image: dxflrs/garage:v1.0.1
|
|
||||||
volumes:
|
|
||||||
- ./garage.toml:/etc/garage.toml
|
|
||||||
- ./meta:/var/lib/garage/meta
|
|
||||||
- ./data:/var/lib/garage/data
|
|
||||||
ports:
|
|
||||||
- 3900:3900 # S3 API
|
|
||||||
- 3901:3901 # RPC
|
|
||||||
- 3902:3902 # S3 Web
|
|
||||||
- 3903:3903 # Admin API
|
|
||||||
|
|
||||||
webui:
|
|
||||||
image: khairul169/garage-webui:latest
|
|
||||||
volumes:
|
|
||||||
- ./garage.toml:/etc/garage.toml:ro
|
|
||||||
ports:
|
|
||||||
- 3909:3909
|
|
||||||
environment:
|
|
||||||
API_BASE_URL: "http://garage:3903"
|
|
||||||
S3_ENDPOINT_URL: "http://garage:3900"
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 2. Standalone Deployment
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker run -p 3909:3909 \
|
|
||||||
-v ./garage.toml:/etc/garage.toml:ro \
|
|
||||||
-e API_BASE_URL="http://garage-host:3903" \
|
|
||||||
-e API_ADMIN_KEY="your-admin-token" \
|
|
||||||
khairul169/garage-webui:latest
|
|
||||||
```
|
|
||||||
|
|
||||||
### 🖥️ Binary Deployment
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Download the binary file
|
|
||||||
wget -O garage-webui https://github.com/khairul169/garage-webui/releases/download/1.0.9/garage-webui-v1.0.9-linux-amd64
|
|
||||||
chmod +x garage-webui
|
|
||||||
|
|
||||||
# Run the service
|
|
||||||
CONFIG_PATH=./garage.toml ./garage-webui
|
|
||||||
```
|
|
||||||
|
|
||||||
### 🔧 SystemD Service
|
|
||||||
|
|
||||||
```ini
|
|
||||||
[Unit]
|
|
||||||
Description=Garage Web UI
|
|
||||||
After=network.target
|
|
||||||
|
|
||||||
[Service]
|
|
||||||
Environment="PORT=3909"
|
|
||||||
Environment="CONFIG_PATH=/etc/garage.toml"
|
|
||||||
ExecStart=/usr/local/bin/garage-webui
|
|
||||||
Restart=always
|
|
||||||
|
|
||||||
[Install]
|
|
||||||
WantedBy=default.target
|
|
||||||
```
|
|
||||||
|
|
||||||
## Configuration Management
|
|
||||||
|
|
||||||
### 📝 Garage Configuration Requirements
|
|
||||||
|
|
||||||
The Web UI requires the Garage cluster to have the Admin API enabled:
|
|
||||||
|
|
||||||
```toml
|
|
||||||
# garage.toml
|
|
||||||
[admin]
|
|
||||||
api_bind_addr = "[::]:3903"
|
|
||||||
admin_token = "your-secure-admin-token"
|
|
||||||
metrics_token = "your-metrics-token" # Optional
|
|
||||||
```
|
|
||||||
|
|
||||||
### 🌍 Environment Variable Configuration
|
|
||||||
|
|
||||||
| Variable Name | Description | Default Value |
|
|
||||||
| ----------------- | ----------------------------- | -------------------- |
|
|
||||||
| `CONFIG_PATH` | Path to Garage config file | `/etc/garage.toml` |
|
|
||||||
| `API_BASE_URL` | Garage Admin API address | Read from config file|
|
|
||||||
| `API_ADMIN_KEY` | Admin API token | Read from config file|
|
|
||||||
| `S3_ENDPOINT_URL` | S3 API address | Read from config file|
|
|
||||||
| `S3_REGION` | S3 region | `garage` |
|
|
||||||
| `BASE_PATH` | Web UI base path | `/` |
|
|
||||||
| `PORT` | Service port | `3909` |
|
|
||||||
| `HOST` | Binding address | `0.0.0.0` |
|
|
||||||
|
|
||||||
### 🔐 Authentication Configuration
|
|
||||||
|
|
||||||
#### Enable Web UI Authentication
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Generate password hash
|
|
||||||
htpasswd -nbBC 10 "admin" "password"
|
|
||||||
|
|
||||||
# Set environment variable
|
|
||||||
AUTH_USER_PASS="admin:$2y$10$DSTi9o..."
|
|
||||||
```
|
|
||||||
|
|
||||||
## Management Best Practices
|
|
||||||
|
|
||||||
### 🚀 Daily Operations
|
|
||||||
|
|
||||||
#### 1. Cluster Health Monitoring
|
|
||||||
|
|
||||||
- **Regular Checks**: Monitor cluster status via the home dashboard
|
|
||||||
- **Alerting Setup**: Configure monitoring systems to connect to the `/metrics` endpoint
|
|
||||||
- **Performance Observation**: Pay attention to storage node connection status and partition health
|
|
||||||
|
|
||||||
#### 2. Bucket Management
|
|
||||||
|
|
||||||
- **Naming Conventions**: Establish uniform bucket naming conventions
|
|
||||||
- **Minimize Permissions**: Assign the minimum necessary permissions to access keys
|
|
||||||
- **Quota Management**: Set appropriate quota limits for important services
|
|
||||||
|
|
||||||
#### 3. Access Control
|
|
||||||
|
|
||||||
- **Regular Rotation**: Rotate API access keys periodically
|
|
||||||
- **Permission Audits**: Regularly review bucket permission assignments
|
|
||||||
- **Key Management**: Create dedicated access keys for different purposes
|
|
||||||
|
|
||||||
### 🔧 Troubleshooting
|
|
||||||
|
|
||||||
#### 1. Connection Issues
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Check Admin API accessibility
|
|
||||||
curl -H "Authorization: Bearer YOUR_TOKEN" \
|
|
||||||
http://garage-host:3903/v2/GetClusterHealth
|
|
||||||
|
|
||||||
# Check network connectivity
|
|
||||||
telnet garage-host 3903
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 2. Configuration Issues
|
|
||||||
|
|
||||||
- Verify the correctness of the `garage.toml` configuration
|
|
||||||
- Confirm that the Admin API port is open
|
|
||||||
- Check firewall and network policies
|
|
||||||
|
|
||||||
#### 3. Performance Optimization
|
|
||||||
|
|
||||||
- Enable caching to reduce API calls
|
|
||||||
- Use a reverse proxy (like Nginx) for SSL termination
|
|
||||||
- Monitor resource usage
|
|
||||||
|
|
||||||
### 📊 Monitoring Integration
|
|
||||||
|
|
||||||
#### Prometheus Metrics
|
|
||||||
|
|
||||||
The Web UI can be configured to monitor Garage's Prometheus metrics:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# prometheus.yml
|
|
||||||
scrape_configs:
|
|
||||||
- job_name: "garage"
|
|
||||||
static_configs:
|
|
||||||
- targets: ["garage-host:3903"]
|
|
||||||
metrics_path: /metrics
|
|
||||||
bearer_token: "your-metrics-token"
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Key Metrics
|
|
||||||
|
|
||||||
- `garage_cluster_health`: Cluster health status
|
|
||||||
- `garage_storage_usage`: Storage usage
|
|
||||||
- `garage_api_requests`: API request statistics
|
|
||||||
- `garage_replication_status`: Data replication status
|
|
||||||
|
|
||||||
## Development Guide
|
|
||||||
|
|
||||||
### 🛠️ Development Environment Setup
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Clone the project
|
|
||||||
git clone https://github.com/khairul169/garage-webui.git
|
|
||||||
cd garage-webui
|
|
||||||
|
|
||||||
# Install frontend dependencies
|
|
||||||
pnpm install
|
|
||||||
|
|
||||||
# Install backend dependencies
|
|
||||||
cd backend && go mod download && cd ..
|
|
||||||
|
|
||||||
# Start the development server
|
|
||||||
pnpm run dev
|
|
||||||
```
|
|
||||||
|
|
||||||
### 🔧 Technology Choices
|
|
||||||
|
|
||||||
- **Frontend**: React 18 + TypeScript + Tailwind CSS
|
|
||||||
- **State Management**: React Query (TanStack Query)
|
|
||||||
- **Routing**: React Router
|
|
||||||
- **UI Components**: Custom component library
|
|
||||||
- **Backend**: Go + Gin framework
|
|
||||||
- **Configuration Parsing**: go-toml
|
|
||||||
|
|
||||||
### 📋 Contribution Guidelines
|
|
||||||
|
|
||||||
1. **Coding Standards**: Follow the project's ESLint and Go fmt standards
|
|
||||||
2. **Testing**: New features require corresponding tests
|
|
||||||
3. **Documentation**: Update relevant documents and API descriptions
|
|
||||||
4. **Compatibility**: Ensure compatibility with the latest version of Garage
|
|
||||||
|
|
||||||
## Security Considerations
|
|
||||||
|
|
||||||
### 🔒 Security Recommendations
|
|
||||||
|
|
||||||
1. **Network Security**
|
|
||||||
|
|
||||||
- Use HTTPS in production environments
|
|
||||||
- Restrict network access to the Admin API
|
|
||||||
- Use firewall rules to protect sensitive ports
|
|
||||||
|
|
||||||
2. **Authentication Security**
|
|
||||||
|
|
||||||
- Consider integrating with an enterprise identity authentication system
|
|
||||||
|
|
||||||
3. **Permission Control**
|
|
||||||
- Follow the principle of least privilege
|
|
||||||
- Use a dedicated administrator token
|
|
||||||
|
|
||||||
## API Features Currently Used by the Project
|
|
||||||
|
|
||||||
**✅ Full API Compliance**: As of July 2025, all API implementations are fully aligned with the official [Garage Admin API v2 specification](https://garagehq.deuxfleurs.fr/api/garage-admin-v2.html). All HTTP methods, request formats, and response handling match the official documentation exactly.
|
|
||||||
|
|
||||||
#### 1. Cluster Management API
|
|
||||||
|
|
||||||
- **`GET /v2/GetClusterHealth`** - Get cluster health status
|
|
||||||
|
|
||||||
- Used on the home dashboard to display cluster status
|
|
||||||
- Monitors the number of connected nodes, storage node status, and partition health
|
|
||||||
|
|
||||||
- **`GET /v2/GetClusterStatus`** - Get detailed cluster status
|
|
||||||
- Used on the cluster management page to display node details
|
|
||||||
- Shows cluster topology and node configuration information
|
|
||||||
|
|
||||||
#### 2. Cluster Layout Management API
|
|
||||||
|
|
||||||
- **`GET /v2/GetClusterLayout`** - Get cluster layout configuration
|
|
||||||
|
|
||||||
- Displays the current cluster layout and staged changes
|
|
||||||
- Views node roles, capacity, and zone assignments
|
|
||||||
|
|
||||||
- **`POST /v2/UpdateClusterLayout`** - Update cluster layout
|
|
||||||
|
|
||||||
- Adds new nodes to the cluster
|
|
||||||
- Modifies node configuration (capacity, zone, tags)
|
|
||||||
- Removes nodes (by setting `remove: true`)
|
|
||||||
|
|
||||||
- **`POST /v2/ConnectClusterNodes`** - Connect cluster nodes
|
|
||||||
|
|
||||||
- Connects new nodes to the cluster
|
|
||||||
- Establishes RPC connections between nodes
|
|
||||||
|
|
||||||
- **`POST /v2/ApplyClusterLayout`** - Apply layout changes
|
|
||||||
|
|
||||||
- Applies staged layout changes to the cluster
|
|
||||||
- Triggers data redistribution
|
|
||||||
|
|
||||||
- **`POST /v2/RevertClusterLayout`** - Revert layout changes
|
|
||||||
- Clears staged layout changes
|
|
||||||
- Restores to the last stable state
|
|
||||||
|
|
||||||
#### 3. Bucket Management API
|
|
||||||
|
|
||||||
- **`GET /v2/ListBuckets`** - List all buckets
|
|
||||||
|
|
||||||
- Gets a list of all buckets in the cluster
|
|
||||||
- Displays basic bucket information and aliases
|
|
||||||
|
|
||||||
- **`GET /v2/GetBucketInfo`** - Get detailed bucket information
|
|
||||||
|
|
||||||
- Views the complete configuration of a single bucket
|
|
||||||
- Includes permissions, statistics, quota information, etc.
|
|
||||||
|
|
||||||
- **`POST /v2/CreateBucket`** - Create a new bucket
|
|
||||||
|
|
||||||
- Supports setting global and local aliases
|
|
||||||
- Configures initial permissions and parameters
|
|
||||||
|
|
||||||
- **`POST /v2/UpdateBucket`** - Update bucket configuration
|
|
||||||
|
|
||||||
- Modifies the bucket's website configuration
|
|
||||||
- Sets or updates quota limits
|
|
||||||
|
|
||||||
- **`POST /v2/DeleteBucket?id={id}`** - Delete bucket
|
|
||||||
- **Implementation**: POST with query parameter (aligned with official specification)
|
|
||||||
- **Parameters**: Bucket ID in query parameter
|
|
||||||
- **Usage**: Remove buckets from cluster
|
|
||||||
|
|
||||||
#### 4. Bucket Alias Management API
|
|
||||||
|
|
||||||
- **`POST /v2/AddBucketAlias`** - Add a global alias
|
|
||||||
- **Implementation**: POST with JSON body (aligned with official specification)
|
|
||||||
- **Parameters**: Bucket ID and alias name in request body (`{ bucketId, globalAlias }`)
|
|
||||||
- **Usage**: Add new bucket aliases
|
|
||||||
|
|
||||||
- **`POST /v2/RemoveBucketAlias`** - Remove a global alias
|
|
||||||
- **Implementation**: POST with JSON body (aligned with official specification)
|
|
||||||
- **Parameters**: Bucket ID and alias name in request body (`{ bucketId, globalAlias }`)
|
|
||||||
- **Usage**: Remove existing bucket aliases
|
|
||||||
|
|
||||||
#### 5. Permission Management API
|
|
||||||
|
|
||||||
- **`POST /v2/AllowBucketKey`** - Grant bucket permissions
|
|
||||||
|
|
||||||
- Assigns bucket operation permissions to an access key
|
|
||||||
- Supports Read, Write, and Owner permissions
|
|
||||||
|
|
||||||
- **`POST /v2/DenyBucketKey`** - Revoke bucket permissions
|
|
||||||
- Removes an access key's permissions for a bucket
|
|
||||||
- Flexible permission control mechanism
|
|
||||||
|
|
||||||
#### 6. Access Key Management API
|
|
||||||
|
|
||||||
- **`GET /v2/ListKeys`** - List all access keys
|
|
||||||
|
|
||||||
- Gets all API keys in the cluster
|
|
||||||
- Displays basic key information
|
|
||||||
|
|
||||||
- **`POST /v2/CreateKey`** - Create a new access key
|
|
||||||
|
|
||||||
- Generates a new S3-compatible access key
|
|
||||||
- Sets initial permissions for the key
|
|
||||||
|
|
||||||
- **`POST /v2/ImportKey`** - Import an existing access key
|
|
||||||
|
|
||||||
- Used for migrating or restoring access keys
|
|
||||||
- Imports externally generated keys
|
|
||||||
|
|
||||||
- **`POST /v2/DeleteKey?id={id}`** - Delete access key
|
|
||||||
- **Implementation**: POST with query parameter (aligned with official specification)
|
|
||||||
- **Parameters**: Key ID in query parameter
|
|
||||||
- **Usage**: Remove access keys from cluster
|
|
||||||
|
|
||||||
### 🔧 Custom Backend Endpoints
|
|
||||||
|
|
||||||
The Garage Web UI implements several custom backend endpoints that extend functionality beyond the standard Garage Admin API:
|
|
||||||
|
|
||||||
#### 1. Configuration Management
|
|
||||||
|
|
||||||
- **`GET /config`** - Get garage configuration
|
|
||||||
- Retrieves garage configuration for frontend display
|
|
||||||
- Provides S3 endpoint URLs, region information, etc.
|
|
||||||
|
|
||||||
#### 2. Authentication System
|
|
||||||
|
|
||||||
- **`POST /auth/login`** - User authentication
|
|
||||||
- Handles user login with username/password
|
|
||||||
- Creates authenticated sessions
|
|
||||||
|
|
||||||
- **`GET /auth/status`** - Authentication status
|
|
||||||
- Checks current authentication state
|
|
||||||
- Returns whether authentication is enabled and user status
|
|
||||||
|
|
||||||
- **`POST /auth/logout`** - User logout
|
|
||||||
- Terminates authenticated sessions
|
|
||||||
- Clears session data
|
|
||||||
|
|
||||||
#### 3. Enhanced Bucket Operations
|
|
||||||
|
|
||||||
- **`GET /buckets`** - Enhanced bucket listing
|
|
||||||
- Provides enriched bucket information by combining `/v2/ListBuckets` and `/v2/GetBucketInfo`
|
|
||||||
- Includes detailed statistics and metadata for all buckets
|
|
||||||
|
|
||||||
#### 4. Object Browser & File Management
|
|
||||||
|
|
||||||
- **`GET /browse/{bucket}`** - Browse bucket objects
|
|
||||||
- Lists objects and folders in a bucket with S3 ListObjectsV2
|
|
||||||
- Supports pagination and prefix filtering
|
|
||||||
- Provides object metadata and download URLs
|
|
||||||
|
|
||||||
- **`GET /browse/{bucket}/{key...}`** - Get/view object
|
|
||||||
- Retrieves object content for viewing or downloading
|
|
||||||
- Supports thumbnail generation for images
|
|
||||||
- Provides object metadata via HeadObject
|
|
||||||
|
|
||||||
- **`PUT /browse/{bucket}/{key...}`** - Upload object
|
|
||||||
- Handles file uploads with multipart form data
|
|
||||||
- Supports directory creation
|
|
||||||
- Uses S3 PutObject for storage
|
|
||||||
|
|
||||||
- **`DELETE /browse/{bucket}/{key...}`** - Delete object/folder
|
|
||||||
- Deletes individual objects or entire folders recursively
|
|
||||||
- Supports bulk deletion for folders
|
|
||||||
- Uses S3 DeleteObject/DeleteObjects
|
|
||||||
|
|
||||||
### 📊 Current Feature Coverage Analysis
|
|
||||||
|
|
||||||
| Feature Category | v2 Total Features | Currently Implemented | Custom Extensions | Total Coverage |
|
|
||||||
| ---------------------- | ----------------- | -------------------- | ---------------- | -------------- |
|
|
||||||
| **Cluster Management** | 6 | 2 | 1 (config) | 50% |
|
|
||||||
| **Layout Management** | 7 | 5 | 0 | 71% |
|
|
||||||
| **Bucket Management** | 9 | 5 | 2 (enhanced list, browse) | 78% |
|
|
||||||
| **Permission Management** | 2 | 2 | 0 | 100% |
|
|
||||||
| **Key Management** | 6 | 4 | 0 | 67% |
|
|
||||||
| **Authentication** | 0 | 0 | 3 (login system) | 100% (custom) |
|
|
||||||
| **File Management** | 0 | 0 | 4 (object browser) | 100% (custom) |
|
|
||||||
| **Advanced Features** | 25+ | 0 | 0 | 0% |
|
|
||||||
| **Overall** | 55+ | 18 | 10 | 51% |
|
|
||||||
|
|
||||||
**Enhanced Coverage**: With custom backend endpoints, the project achieves 51% total feature coverage, providing comprehensive cluster management, authentication, and file browsing capabilities.
|
|
||||||
|
|
||||||
### 🚀 Available v2 Features Not Yet Implemented
|
|
||||||
|
|
||||||
The project can further enhance functionality by implementing these additional v2 API features:
|
|
||||||
|
|
||||||
#### 1. Admin Token Management
|
|
||||||
- `GET /v2/ListAdminTokens` - List all admin tokens
|
|
||||||
- `GET /v2/GetAdminTokenInfo` - Get token information
|
|
||||||
- `GET /v2/GetCurrentAdminTokenInfo` - Get current token information
|
|
||||||
- `POST /v2/CreateAdminToken` - Create an admin token
|
|
||||||
- `POST /v2/UpdateAdminToken/{id}` - Update an admin token
|
|
||||||
- `POST /v2/DeleteAdminToken/{id}` - Delete an admin token
|
|
||||||
|
|
||||||
#### 2. Enhanced Node Management
|
|
||||||
- `GET /v2/GetNodeInfo/{node}` - Get node information
|
|
||||||
- `GET /v2/GetNodeStatistics/{node}` - Get node statistics
|
|
||||||
- `POST /v2/CreateMetadataSnapshot/{node}` - Create a metadata snapshot
|
|
||||||
- `POST /v2/LaunchRepairOperation/{node}` - Launch a repair operation
|
|
||||||
|
|
||||||
#### 3. Worker Process Management
|
|
||||||
- `POST /v2/ListWorkers/{node}` - List worker processes
|
|
||||||
- `POST /v2/GetWorkerInfo/{node}` - Get worker process information
|
|
||||||
- `POST /v2/GetWorkerVariable/{node}` - Get a worker process variable
|
|
||||||
- `POST /v2/SetWorkerVariable/{node}` - Set a worker process variable
|
|
||||||
|
|
||||||
#### 4. Advanced Block Management
|
|
||||||
- `POST /v2/GetBlockInfo/{node}` - Get block information
|
|
||||||
- `GET /v2/ListBlockErrors/{node}` - List block errors
|
|
||||||
- `POST /v2/RetryBlockResync/{node}` - Retry a block resync
|
|
||||||
- `POST /v2/PurgeBlocks/{node}` - Purge blocks
|
|
||||||
|
|
||||||
#### 5. Enhanced Bucket Features
|
|
||||||
- `POST /v2/CleanupIncompleteUploads` - Cleanup incomplete uploads
|
|
||||||
- `GET /v2/InspectObject` - Inspect object details
|
|
||||||
- `GET /v2/GetClusterStatistics` - Get cluster-level statistics
|
|
||||||
- `POST /v2/PreviewClusterLayoutChanges` - Preview layout changes
|
|
||||||
- `GET /v2/GetClusterLayoutHistory` - Get layout history
|
|
||||||
|
|
||||||
### 🎯 Future Development Roadmap
|
|
||||||
|
|
||||||
#### 📅 Short-Term (1-2 months)
|
|
||||||
1. **Enhanced Monitoring**: Implement cluster statistics and node information display
|
|
||||||
2. **Layout Improvements**: Add layout history viewing and change preview functionality
|
|
||||||
3. **Object Management**: Add object inspection and incomplete upload cleanup
|
|
||||||
|
|
||||||
#### 📅 Medium-Term (3-6 months)
|
|
||||||
1. **Admin Token Management**: Full admin token lifecycle management interface
|
|
||||||
2. **Advanced Monitoring**: Worker process monitoring and detailed node statistics
|
|
||||||
3. **Maintenance Tools**: Automated repair operations and block management
|
|
||||||
|
|
||||||
#### 📅 Long-Term (6+ months)
|
|
||||||
1. **Complete API Coverage**: Implement all available v2 API endpoints
|
|
||||||
2. **Advanced Bulk Operations**: Comprehensive bulk management features
|
|
||||||
3. **Real-time Integration**: WebSocket support for live updates and monitoring
|
|
||||||
|
|
||||||
**Current Status**: The Garage Web UI successfully uses Garage Admin API v2 with 18 standard endpoints plus 10 custom backend endpoints, achieving 51% feature coverage. The project provides a comprehensive management interface with cluster administration, authentication, file browsing, and enhanced bucket management capabilities, serving as a robust web-based alternative to command-line tools.
|
|
||||||
|
|
||||||
**Implementation Philosophy**: The project prioritizes REST API compliance and user experience, which may result in HTTP method choices that differ from the official specification while maintaining full functional compatibility.
|
|
||||||
Loading…
x
Reference in New Issue
Block a user