# 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