From bd5b1e645a3c5ad0bc35f0f6eeb1037929920e14 Mon Sep 17 00:00:00 2001 From: MayaChat Date: Mon, 24 Nov 2025 13:05:57 -0500 Subject: [PATCH] Add comprehensive Quick Reference guide for Services Homepage --- QUICK-REFERENCE.md | 272 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 272 insertions(+) create mode 100644 QUICK-REFERENCE.md diff --git a/QUICK-REFERENCE.md b/QUICK-REFERENCE.md new file mode 100644 index 0000000..655f5b6 --- /dev/null +++ b/QUICK-REFERENCE.md @@ -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 + +``` + +Then rebuild: +```bash +docker compose restart services-homepage +``` + +### Custom Health Check Path + +For services with non-root health endpoints: + +```xml + +``` + +### Override Health Check IP + +Use local IP instead of Tailscale: + +```xml + +``` + +### Disable Health Check + +For services that don't support HEAD requests: + +```xml + +``` + +--- + +## 🎛️ 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