Homepage/QUICK-REFERENCE.md

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:

<service 
  id="myservice"
  name="My Service"
  proto="http"
  port="8080"
  logo="mylogo.svg"
/>

Then rebuild:

docker compose restart services-homepage

Custom Health Check Path

For services with non-root health endpoints:

<service 
  id="myapi"
  health-path="/api/health"
/>

Override Health Check IP

Use local IP instead of Tailscale:

<service 
  id="myservice"
  local-ip="192.168.1.100"
/>

Disable Health Check

For services that don't support HEAD requests:

<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

localStorage.removeItem('services-order');
location.reload();

Reset Collapsed Groups

localStorage.removeItem('collapsed-groups');
location.reload();

Reset Theme

localStorage.removeItem('selected-theme');
location.reload();

Reset Widgets

localStorage.removeItem('enabled-widgets');
location.reload();

Reset Everything

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

cd /home/mayatheshy/dockercompose/services-homepage
docker compose down
docker compose up -d

View Logs

docker logs services-homepage --tail 50
docker logs services-homepage-health-proxy --tail 50

Test Health Endpoint

curl http://192.168.2.180:8088/healthcheck?id=SERVICE_ID

Edit Configuration

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