From 748da472359f4c2799319a999556b821866bfb06 Mon Sep 17 00:00:00 2001 From: MayaChat Date: Sun, 23 Nov 2025 23:38:11 -0500 Subject: [PATCH] Made a README file. --- README.md | 340 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 339 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 0d10b6f..b20d8d9 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,340 @@ -# Homepage +# Services Homepage +A lightweight, self-hosted dashboard for quick access to your Docker services with a modern holographic UI design. + +![License](https://img.shields.io/badge/license-MIT-blue.svg) +![Docker](https://img.shields.io/badge/docker-required-blue.svg) + +## Features + +- 🎨 **Holographic Glass Design** - Modern liquid glass buttons with animated shimmer effects +- 🎯 **Dynamic Service Loading** - Services configured via simple XML file +- 🔍 **Smart URL Resolution** - Automatic handling of ports, protocols, and hostnames +- 🎭 **Icon Integration** - Includes Simple Icons pack (3000+ brand logos) +- 📱 **Responsive Layout** - Works seamlessly on desktop and mobile +- 🐳 **Docker-Ready** - Single-container deployment with nginx +- ⚡ **Lightweight** - Minimal resources, fast loading + +## Quick Start + +### 1. Deploy with Docker Compose + +```bash +docker-compose up -d +``` + +The homepage will be available at `http://localhost:8088` + +### 2. Configure Your Services + +Edit `services.xml` to add your services: + +```xml + + + + + +``` + +### 3. Restart to Apply Changes + +```bash +docker-compose restart +``` + +## Configuration Guide + +### Service Attributes + +| Attribute | Required | Description | Example | +|-----------|----------|-------------|---------| +| `name` | Yes | Display name for the service | `"Nextcloud"` | +| `proto` | No | Protocol (http/https) | `"https"` (default: `"http"`) | +| `port` | No | Port number | `"8080"` | +| `host` | No | Custom hostname or full URL | `"nextcloud.example.com"` | +| `logo` | No | Icon filename in `/logos/` | `"nextcloud.svg"` | + +### URL Resolution Logic + +The service URL is built using this priority: + +1. **Full URL** - If `host` starts with `http://` or `https://`, use as-is +2. **Hostname with Port** - If `host` contains `:port`, use `proto://host:port` +3. **Hostname Only** - If `host` is set (no port), use `https://host` (ignores `proto` and `port`) +4. **Fallback** - Use current page hostname with specified `proto` and `port` + +### Examples + +```xml + + + + + + + + + + + +``` + +## Icon Management + +### Using Included Icons + +The repository includes Simple Icons (3000+ brand logos). Available icons are in: +``` +logos/simple-icons/icons/ +``` + +### Adding Custom Icons + +1. Add your SVG file to the `logos/` directory +2. Reference it in `services.xml`: +```xml + +``` + +### Icon Styling + +All icons are automatically styled white using CSS filters. To customize: + +Edit `styles.css` and modify the `.card .logo` rule: +```css +.card .logo { + filter: brightness(0) invert(1); /* White icons */ + /* OR */ + filter: hue-rotate(180deg); /* Color shift */ +} +``` + +## Customization + +### Theme Colors + +Edit CSS variables in `styles.css`: + +```css +:root { + --bg: #0f1720; /* Background color */ + --card: #0b1220; /* Card background */ + --accent: #4f46e5; /* Accent color (purple) */ + --muted: #94a3b8; /* Muted text */ +} +``` + +### Holographic Effects + +The holographic button effects include: +- **Shimmer Animation** - Continuous light sweep (8s loop, 3s on hover) +- **Gradient Background** - Purple/pink gradient blend +- **Glowing Border** - Animated gradient border on hover +- **Backdrop Blur** - Glass-like frosted effect + +To adjust shimmer speed, modify the `@keyframes shimmer` animation: +```css +.card::before { + animation: shimmer 8s infinite linear; /* Change 8s to adjust speed */ +} +``` + +### Layout + +Change grid responsiveness in `styles.css`: +```css +.grid { + grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); + /* Adjust minmax() to change card width */ +} +``` + +## File Structure + +``` +services-homepage/ +├── docker-compose.yml # Docker deployment config +├── Dockerfile # Custom nginx build (if needed) +├── index.html # Main HTML page +├── styles.css # Holographic UI styles +├── services.xml # Service definitions +├── README.md # This file +├── LICENSE # License information +└── logos/ # Icon directory + ├── simple-icons/ # Simple Icons pack (3000+ logos) + ├── default.svg # Fallback icon + ├── gitea.svg + ├── jellyfin.svg + ├── nextcloud.svg + └── ... +``` + +## Updating Icons + +### Replace All Icons with Simple Icons + +```bash +cd logos +for f in *.svg; do + basename=$(basename "$f" .svg) + match=$(find simple-icons/icons -type f -iname "*${basename}*.svg" -print -quit) + [ -n "$match" ] && cp "$match" "$f" && echo "Updated: $f" +done +``` + +### Find Available Icons + +```bash +ls logos/simple-icons/icons/ | grep -i "keyword" +``` + +## Backup and Recovery + +Icon backups are automatically created in: +``` +logos/backup-YYYYMMDD-HHMMSS/ +``` + +To restore from backup: +```bash +cp logos/backup-20251123-231406/*.svg logos/ +docker-compose restart +``` + +## Troubleshooting + +### Services Not Loading + +1. Check `services.xml` syntax: +```bash +xmllint --noout services.xml +``` + +2. Check browser console for errors (F12) + +3. Verify file permissions: +```bash +chmod 644 services.xml index.html styles.css +chmod 755 logos/ +``` + +### Icons Not Displaying + +1. Verify icon exists: +```bash +ls -lh logos/youricon.svg +``` + +2. Check icon reference in `services.xml` matches filename exactly + +3. Clear browser cache (Ctrl+Shift+R) + +### Container Issues + +```bash +# View logs +docker logs services-homepage + +# Restart container +docker-compose restart + +# Rebuild if files changed +docker-compose up -d --force-recreate +``` + +## Performance + +- **Image Size**: ~45MB (nginx:alpine base) +- **Memory Usage**: ~5-10MB +- **Load Time**: <100ms (local network) +- **Icons**: Cached by browser after first load + +## Browser Support + +- ✅ Chrome/Edge 90+ +- ✅ Firefox 88+ +- ✅ Safari 14+ +- ✅ Mobile browsers (iOS Safari, Chrome Android) + +## Security + +- All volumes mounted read-only (`:ro`) +- No external dependencies at runtime +- Logs automatically rotated (5MB max, 2 files) +- CORS not enabled (same-origin only) + +## Advanced Usage + +### Custom Nginx Config + +Create `nginx.conf` and mount it: + +```yaml +volumes: + - ./nginx.conf:/etc/nginx/nginx.conf:ro +``` + +### Adding Authentication + +Use a reverse proxy (Nginx Proxy Manager, Caddy, Traefik) with basic auth: + +```nginx +location / { + auth_basic "Services"; + auth_basic_user_file /etc/nginx/.htpasswd; + proxy_pass http://services-homepage:80; +} +``` + +### Dynamic Port Updates + +For services with dynamic ports (e.g., Transmission behind VPN), use environment variables: + +```xml + +``` + +Then update via script or use a template processor. + +## Contributing + +Contributions welcome! Areas for improvement: +- Search/filter functionality +- Dark/light mode toggle +- Service health checks +- Drag-and-drop reordering +- Categorized sections + +## License + +MIT License - See LICENSE file for details + +## Credits + +- **Icons**: [Simple Icons](https://simpleicons.org/) (CC0 1.0 Universal) +- **Design Inspiration**: Holographic UI by vishnu137 on CodePen +- **Web Server**: nginx Alpine + +## Support + +For issues, questions, or suggestions: +1. Check this README first +2. Review browser console for errors +3. Check Docker logs: `docker logs services-homepage` +4. Verify `services.xml` syntax + +--- + +**Version**: 1.0.0 +**Last Updated**: November 23, 2025 \ No newline at end of file