188 lines
4.9 KiB
Markdown
188 lines
4.9 KiB
Markdown
# GlobalQuota - Nextcloud App v1.2.1
|
|
|
|
Define and monitor a global storage quota, compatible with S3 and external storage.
|
|
|
|
**NEW v1.2.1**: Enhanced UI reliability with fallback text display and improved debugging.
|
|
**NEW v1.2.0**: Adaptive visualization with ServerInfo integration or standalone Chart.js donut.
|
|
**NEW v1.1.0**: Blocks uploads when global quota is exceeded.
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
* ✅ **Global quota definition and monitoring**
|
|
* ✅ **Compatible with S3 and external storage backends**
|
|
* ✅ **Upload blocking when quota exceeded** (PSR-14 events)
|
|
* ✅ **OCC commands** for management
|
|
* ✅ **REST API** for external integration
|
|
* ✅ **Server Info dashboard integration**
|
|
* ✅ **Adaptive visualization (v1.2.0)**:
|
|
+ Integrates seamlessly into ServerInfo if supported
|
|
+ Shows its own donut chart in Admin Settings otherwise
|
|
* ✅ **Enhanced reliability (v1.2.1)**:
|
|
+ Always displays quota values in text format
|
|
+ Robust error handling and debugging logs
|
|
+ Chart.js fallback mechanisms
|
|
|
|
---
|
|
|
|
### Admin Settings Panel
|
|
The app displays quota information with both visual chart and text values:
|
|
- **Used storage**: Shows current usage
|
|
- **Free storage**: Available space remaining
|
|
- **Total storage**: Global quota limit
|
|
- **Usage percentage**: Visual indicator with color coding
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
1. **Download** or clone this repository
|
|
2. **Copy** the `globalquota` folder to your Nextcloud `apps/` directory
|
|
3. **Enable** the app in Nextcloud Admin Settings → Apps
|
|
4. **Configure** the global quota in Admin Settings → Additional Settings → Global Quota
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
Add to `config/config.php`:
|
|
|
|
```php
|
|
'globalquota' => [
|
|
'enabled' => true,
|
|
'quota_bytes' => 500 * 1024 * 1024 * 1024, // 500 GB
|
|
],
|
|
```
|
|
|
|
---
|
|
|
|
## OCC Commands
|
|
|
|
```bash
|
|
# Set quota (in bytes)
|
|
occ globalquota:set 2147483648 # 2 GB
|
|
|
|
# Check status
|
|
occ globalquota:status
|
|
|
|
# Force recalculation
|
|
occ globalquota:recalc
|
|
```
|
|
|
|
---
|
|
|
|
## API Endpoints
|
|
|
|
```bash
|
|
# Get current status (new endpoint for admin chart)
|
|
curl -H "Authorization: Bearer TOKEN" \
|
|
https://instance.com/apps/globalquota/status
|
|
|
|
# Legacy API v1 endpoint
|
|
curl -H "Authorization: Bearer TOKEN" \
|
|
https://instance.com/apps/globalquota/api/v1/status
|
|
|
|
# Update quota
|
|
curl -X PUT \
|
|
-H "Authorization: Bearer TOKEN" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"quota_bytes": 10737418240}' \
|
|
https://instance.com/apps/globalquota/api/v1/quota
|
|
```
|
|
|
|
---
|
|
|
|
## Upload Blocking
|
|
|
|
When the global quota is exceeded, the app will:
|
|
|
|
* ❌ **Block new file uploads**
|
|
* ❌ **Block file updates that increase size**
|
|
* 🚫 **Return HTTP 507 "Insufficient Storage" error**
|
|
* 📱 **Work with all clients** (web, desktop, mobile, WebDAV)
|
|
|
|
---
|
|
|
|
## Visualization Modes
|
|
|
|
### 🔗 **With ServerInfo Integration**
|
|
If ServerInfo supports events (`LoadAdditionalDataEvent`), GlobalQuota **replaces the Disk chart** with GlobalQuota data.
|
|
|
|
### 📊 **Standalone Mode**
|
|
If ServerInfo does not support events, GlobalQuota shows its **own donut chart** in the Admin Settings section.
|
|
|
|
### 📝 **Text Fallback (v1.2.1)**
|
|
Even if the chart fails to load, quota values are **always displayed in text format** for reliability.
|
|
|
|
**Both modes display:**
|
|
- Usage percentage with color coding
|
|
- Used / Free / Total values (formatted)
|
|
- Auto-refresh capability via "Refresh" button
|
|
- Detailed console logging for debugging
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Chart not displaying?
|
|
1. Check browser console for errors (`F12` → Console)
|
|
2. Look for `GlobalQuota:` log messages
|
|
3. Verify Chart.js is loading (CDN or local)
|
|
4. Text values should still display regardless
|
|
|
|
### API errors?
|
|
1. Verify app is enabled and configured
|
|
2. Check Nextcloud logs for backend errors
|
|
3. Test endpoints directly with curl
|
|
|
|
---
|
|
|
|
## Requirements
|
|
|
|
* **Nextcloud 25+**
|
|
* **Admin privileges** for configuration
|
|
* **Optional**: ServerInfo app (for dashboard integration)
|
|
* **Browser**: Modern browser with JavaScript enabled
|
|
|
|
---
|
|
|
|
## Changelog
|
|
|
|
* **v1.2.1** *(Latest)*
|
|
+ Enhanced UI reliability with always-visible text values
|
|
+ Improved error handling and debugging logs
|
|
+ Chart.js fallback mechanisms
|
|
+ Better console logging for troubleshooting
|
|
|
|
* **v1.2.0**
|
|
+ Adaptive visualization (ServerInfo integration or standalone Chart.js donut)
|
|
+ New `/apps/globalquota/status` endpoint
|
|
+ Improved admin settings panel
|
|
|
|
* **v1.1.0**
|
|
+ Upload blocking functionality with PSR-14 events
|
|
+ OCC commands and REST API integration
|
|
|
|
* **v1.0.0**
|
|
+ Initial release with basic quota management and S3 compatibility
|
|
|
|
---
|
|
|
|
## Contributing
|
|
|
|
1. **Fork** this repository
|
|
2. **Create** a feature branch
|
|
3. **Make** your changes
|
|
4. **Test** thoroughly
|
|
5. **Submit** a pull request
|
|
|
|
### Reporting Issues
|
|
Please report bugs and feature requests on [GitHub Issues](https://github.com/DavidCamejo/globalquota/issues).
|
|
|
|
---
|
|
|
|
**Author:** David Camejo
|
|
**License:** AGPL-3.0
|
|
**Repository:** https://github.com/DavidCamejo/globalquota
|