273 lines
5.3 KiB
Markdown
273 lines
5.3 KiB
Markdown
# 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
|