# Services Homepage - FAQ

## 🚀 Quick Start

**Q: How do I access my services?**  
A: Click any service card to open it in a new tab. Local services use your network, public ones go to their domains.

**Q: What do the colored dots mean?**  
A: 🟢 Green = Online | 🔴 Red = Offline | 🟠 Orange = Maintenance | ⚪ Gray = Checking

---

## 🔍 Search & Navigation

**Q: How do I search services?**  
A: Type in the search bar to filter. Press `/` to focus search. Press Enter to search on DuckDuckGo.

**Q: Can I use keyboard navigation?**  
A: Yes! Use arrow keys (↑ ↓ ← →) to navigate, Enter to open a service.

---

## 🎨 Customization

**Q: How do I change the theme?**  
A: Click the 🎨 icon (top-right) and select from 5 themes: Dark, Light, Ocean, Sunset, Forest.

**Q: Can I reorder services?**  
A: Yes! Drag and drop any service card within its group. Order is saved automatically.

**Q: How do I collapse groups?**  
A: Click any group header to collapse/expand. State persists across sessions.

---

## 📊 Widgets

**Q: How do I enable the weather widget?**  
A: 1) Get a free API key from [OpenWeatherMap](https://openweathermap.org/api)  
2) Click ⚙️ Widgets → Enable Weather → Enter API key → Save & Reload

**Q: What widgets are available?**  
A: Clock (real-time), Weather (requires API key), Daily Quote (random quotes)

---

## 💾 Backup & Configuration

**Q: How do I backup my configuration?**  
A: Click 📥 Export (top-left) to download a JSON backup of all services.

**Q: How do I restore a backup?**  
A: Click 📤 Import → Select JSON file → Download the generated services.xml → Replace your file and rebuild.

**Q: How do I add a new service?**  
A: Edit `services.xml`, add a `<service>` element in a group, then run `docker restart services-homepage`

---

## 🔧 Troubleshooting

**Q: Service shows offline but it's running?**  
A: The service might not respond to health checks. Add `check-health="false"` to disable checking.

**Q: Health check needs a custom path?**  
A: Add `health-path="/your/path"` to the service in services.xml (e.g., `health-path="/api/health"`).

**Q: How do I reset everything?**  
A: Open browser console (F12) and run: `localStorage.clear(); location.reload();`

**Q: Widgets not appearing?**  
A: Check browser console for errors. For weather, verify your API key is correct.

---

## 🔑 Keyboard Shortcuts

- `/` - Focus search
- `↑` `↓` `←` `→` - Navigate services  
- `Enter` - Open selected service / Search DuckDuckGo
- `Esc` - Clear search

---

## 📝 Quick Commands

**Add a service:**
```xml
<service id="myapp" name="My App" proto="http" port="8080" logo="myapp.svg" />
```

**Rebuild homepage:**
```bash
docker restart services-homepage
```

**View logs:**
```bash
docker logs services-homepage --tail 50
```

---

## 🔗 Quick Links

- Full Documentation: [FEATURES.md](FEATURES.md)
- Quick Reference: [QUICK-REFERENCE.md](QUICK-REFERENCE.md)
- Get Weather API Key: [OpenWeatherMap](https://openweathermap.org/api)

---

**Need more help?** Check the full README.md or documentation files.