Add comprehensive Quick Reference guide for Services Homepage
This commit is contained in:
MayaChat
272
QUICK-REFERENCE.md
Normal file
272
QUICK-REFERENCE.md
Normal file
@@ -0,0 +1,272 @@
|
||||
# Services Homepage - Quick Reference
|
||||
|
||||
## 🎯 Quick Start
|
||||
|
||||
### Access Your Homepage
|
||||
- Local: `http://192.168.2.180:8088`
|
||||
- Public: `https://homepage.spatulaa.com`
|
||||
|
||||
### Essential Keyboard Shortcuts
|
||||
- `↑` `↓` `←` `→` - Navigate between services
|
||||
- `Enter` - Open selected service
|
||||
- Type to search - Instant filter
|
||||
|
||||
---
|
||||
|
||||
## 🎨 UI Controls
|
||||
|
||||
### Header Controls (Top-Right)
|
||||
- **🎨 Theme Selector** - Change visual theme
|
||||
- Click icon → Select from 5 themes
|
||||
- Dark, Light, Ocean, Sunset, Forest
|
||||
|
||||
### Header Controls (Top-Left)
|
||||
- **📥 Export** - Backup configuration to JSON
|
||||
- **📤 Import** - Restore from JSON backup
|
||||
- **⚙️ Widgets** - Configure dashboard widgets
|
||||
|
||||
### Service Groups
|
||||
- **Click Group Header** - Collapse/expand group
|
||||
- **▼ Icon** - Visual collapse indicator
|
||||
|
||||
### Service Cards
|
||||
- **Drag & Drop** - Reorder within same group
|
||||
- **Status Dot** (top-right) - Health indicator
|
||||
- 🟢 Green (pulsing) = Online
|
||||
- 🔴 Red = Offline
|
||||
- 🟠 Orange = Maintenance
|
||||
- ⚪ Gray (spinning) = Checking
|
||||
- **ⓘ Info Button** (bottom-right) - Connection details
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Configuration Cheat Sheet
|
||||
|
||||
### Add a New Service
|
||||
|
||||
Edit `services.xml`:
|
||||
|
||||
```xml
|
||||
<service
|
||||
id="myservice"
|
||||
name="My Service"
|
||||
proto="http"
|
||||
port="8080"
|
||||
logo="mylogo.svg"
|
||||
/>
|
||||
```
|
||||
|
||||
Then rebuild:
|
||||
```bash
|
||||
docker compose restart services-homepage
|
||||
```
|
||||
|
||||
### Custom Health Check Path
|
||||
|
||||
For services with non-root health endpoints:
|
||||
|
||||
```xml
|
||||
<service
|
||||
id="myapi"
|
||||
health-path="/api/health"
|
||||
/>
|
||||
```
|
||||
|
||||
### Override Health Check IP
|
||||
|
||||
Use local IP instead of Tailscale:
|
||||
|
||||
```xml
|
||||
<service
|
||||
id="myservice"
|
||||
local-ip="192.168.1.100"
|
||||
/>
|
||||
```
|
||||
|
||||
### Disable Health Check
|
||||
|
||||
For services that don't support HEAD requests:
|
||||
|
||||
```xml
|
||||
<service
|
||||
id="myservice"
|
||||
check-health="false"
|
||||
/>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎛️ Widget Configuration
|
||||
|
||||
### Enable Clock Widget
|
||||
1. Click **⚙️ Widgets**
|
||||
2. Check **🕐 Clock**
|
||||
3. Click **Save & Reload**
|
||||
|
||||
### Enable Weather Widget
|
||||
1. Get free API key: https://openweathermap.org/api
|
||||
2. Click **⚙️ Widgets**
|
||||
3. Check **🌤️ Weather**
|
||||
4. Enter API key
|
||||
5. Set location (`auto` or city name)
|
||||
6. Click **Save & Reload**
|
||||
|
||||
### Enable Daily Quote
|
||||
1. Click **⚙️ Widgets**
|
||||
2. Check **💭 Daily Quote**
|
||||
3. Click **Save & Reload**
|
||||
|
||||
---
|
||||
|
||||
## 💾 Backup & Restore
|
||||
|
||||
### Export Configuration
|
||||
1. Click **📥 Export**
|
||||
2. Save JSON file
|
||||
3. Store safely
|
||||
|
||||
### Import Configuration
|
||||
1. Click **📤 Import**
|
||||
2. Select JSON file
|
||||
3. Download generated `services.xml`
|
||||
4. Replace file and rebuild
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Reset Functions
|
||||
|
||||
### Reset Service Order
|
||||
```javascript
|
||||
localStorage.removeItem('services-order');
|
||||
location.reload();
|
||||
```
|
||||
|
||||
### Reset Collapsed Groups
|
||||
```javascript
|
||||
localStorage.removeItem('collapsed-groups');
|
||||
location.reload();
|
||||
```
|
||||
|
||||
### Reset Theme
|
||||
```javascript
|
||||
localStorage.removeItem('selected-theme');
|
||||
location.reload();
|
||||
```
|
||||
|
||||
### Reset Widgets
|
||||
```javascript
|
||||
localStorage.removeItem('enabled-widgets');
|
||||
location.reload();
|
||||
```
|
||||
|
||||
### Reset Everything
|
||||
```javascript
|
||||
localStorage.clear();
|
||||
location.reload();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Common Issues
|
||||
|
||||
### Health Checks Fail (502)
|
||||
- **Cause:** Nginx can't resolve health-proxy
|
||||
- **Fix:** Ensure `nginx.conf` has `resolver 127.0.0.11;`
|
||||
- **Apply:** `docker restart services-homepage`
|
||||
|
||||
### Service Shows Offline (But It's Running)
|
||||
- **Check:** Health check path correct?
|
||||
- **Fix:** Add `health-path="/custom/path"`
|
||||
- **Or:** Set `check-health="false"` and use `status="online"`
|
||||
|
||||
### Widgets Not Loading
|
||||
- **Weather:** Verify API key is valid
|
||||
- **Check:** Browser console for errors
|
||||
- **Try:** Disable and re-enable in settings
|
||||
|
||||
### Drag-Drop Not Working
|
||||
- **Check:** JavaScript enabled?
|
||||
- **Try:** Different browser
|
||||
- **Reset:** Clear localStorage
|
||||
|
||||
### Theme Not Saving
|
||||
- **Check:** Browser allows localStorage
|
||||
- **Try:** Disable private/incognito mode
|
||||
- **Fix:** Check browser storage settings
|
||||
|
||||
---
|
||||
|
||||
## 📊 Health Check Priority
|
||||
|
||||
When multiple IPs are configured, health checks use this priority:
|
||||
|
||||
1. `local-ip` (service-specific)
|
||||
2. `tailscale-ip` (global root attribute)
|
||||
3. `host` (parsed from host attribute)
|
||||
4. Current browser hostname
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Pro Tips
|
||||
|
||||
### Organize Services
|
||||
- Use groups to categorize (Management, Media, Development, etc.)
|
||||
- Drag-drop to prioritize frequently used services
|
||||
- Collapse rarely used groups
|
||||
|
||||
### Theme Switching
|
||||
- Use **Dark** for nighttime browsing
|
||||
- Use **Light** for daytime
|
||||
- Try **Ocean** for reduced eye strain
|
||||
|
||||
### Performance
|
||||
- Disable health checks for very slow services
|
||||
- Use `health-path` to point to lightweight endpoints
|
||||
- Collapse large groups when not needed
|
||||
|
||||
### Backup Strategy
|
||||
- Export configuration monthly
|
||||
- Store JSON files in version control (Git)
|
||||
- Keep backup before major changes
|
||||
|
||||
---
|
||||
|
||||
## 📞 Quick Commands
|
||||
|
||||
### Rebuild Homepage
|
||||
```bash
|
||||
cd /home/mayatheshy/dockercompose/services-homepage
|
||||
docker compose down
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### View Logs
|
||||
```bash
|
||||
docker logs services-homepage --tail 50
|
||||
docker logs services-homepage-health-proxy --tail 50
|
||||
```
|
||||
|
||||
### Test Health Endpoint
|
||||
```bash
|
||||
curl http://192.168.2.180:8088/healthcheck?id=SERVICE_ID
|
||||
```
|
||||
|
||||
### Edit Configuration
|
||||
```bash
|
||||
nano services.xml
|
||||
docker restart services-homepage
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Useful Links
|
||||
|
||||
- OpenWeatherMap API: https://openweathermap.org/api
|
||||
- Quotable API: https://api.quotable.io/random
|
||||
- Simple Icons: https://simpleicons.org/ (for logos)
|
||||
- Three.js Docs: https://threejs.org/docs/
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2025-11-24
|
||||
**Version:** 2.0.0
|
||||
Reference in New Issue
Block a user