Files
EZ-Homelab/wiki/service-docs/homepage.md
kelinfoxy ef55974b50 Wiki major update
updated with recent documentation
2026-01-21 19:18:39 -05:00

838 lines
18 KiB
Markdown

# Homepage - Application Dashboard
## Table of Contents
- [Overview](#overview)
- [What is Homepage?](#what-is-homepage)
- [Why Use Homepage?](#why-use-homepage)
- [How It Works](#how-it-works)
- [Configuration in AI-Homelab](#configuration-in-ai-homelab)
- [Official Resources](#official-resources)
- [Educational Resources](#educational-resources)
- [Docker Configuration](#docker-configuration)
- [Configuration Guide](#configuration-guide)
- [Widgets and Integrations](#widgets-and-integrations)
- [Advanced Topics](#advanced-topics)
- [Troubleshooting](#troubleshooting)
## Overview
**Category:** Dashboard
**Docker Image:** [ghcr.io/gethomepage/homepage](https://github.com/gethomepage/homepage/pkgs/container/homepage)
**Default Stack:** `dashboards.yml`
**Web UI:** `https://homepage.${DOMAIN}` or `http://SERVER_IP:3000`
**Authentication:** Optional (use Authelia for protection)
**Purpose:** Unified dashboard for all homelab services
## What is Homepage?
Homepage is a modern, highly customizable application dashboard designed for homelabs. It provides a clean interface to access all your services with real-time status monitoring, API integrations, and customizable widgets.
### Key Features
- **Service Cards:** Organize services with icons, descriptions, and links
- **Live Status:** Health checks and uptime monitoring
- **API Integrations:** Real-time data from 100+ services
- **Widgets:** Weather, Docker stats, system resources, bookmarks
- **Customizable:** YAML-based configuration
- **Fast & Lightweight:** Minimal resource usage
- **Modern UI:** Clean, responsive design
- **Dark/Light Mode:** Theme options
- **Search:** Quick service filtering
- **Docker Integration:** Auto-discover containers
- **Bookmarks:** Quick links and resources
- **Multi-Language:** i18n support
## Why Use Homepage?
1. **Central Hub:** Single page for all homelab services
2. **Visual Overview:** See everything at a glance
3. **Status Monitoring:** Know which services are up/down
4. **Quick Access:** Fast navigation to services
5. **Beautiful Design:** Modern, polished interface
6. **Easy Configuration:** Simple YAML files
7. **Active Development:** Regular updates and improvements
8. **API Integration:** Real-time service stats
9. **Customizable:** Tailor to your needs
10. **Free & Open Source:** Community-driven
## How It Works
```
User → Browser → Homepage Dashboard
┌─────────┴─────────┐
↓ ↓
Service Cards Widgets
(with icons) (live data)
↓ ↓
Click to access API integrations
service URL (Plex, Sonarr, etc.)
```
### Architecture
**Configuration Structure:**
```
/config/
├── settings.yaml # Global settings
├── services.yaml # Service definitions
├── widgets.yaml # Dashboard widgets
├── bookmarks.yaml # Quick links
├── docker.yaml # Docker integration
└── custom.css # Custom styling (optional)
```
**Data Flow:**
1. **Homepage loads** configuration files
2. **Renders dashboard** with service cards
3. **Makes API calls** to configured services
4. **Displays live data** in widgets
5. **Health checks** verify service status
6. **Updates in real-time** (configurable interval)
## Configuration in AI-Homelab
### Directory Structure
```
/opt/stacks/dashboards/homepage/config/
├── settings.yaml
├── services.yaml
├── widgets.yaml
├── bookmarks.yaml
└── docker.yaml
```
### Environment Variables
```bash
# Optional: Custom port
PORT=3000
# Optional: Puid/Pgid for permissions
PUID=1000
PGID=1000
```
## Official Resources
- **Website:** https://gethomepage.dev
- **GitHub:** https://github.com/gethomepage/homepage
- **Documentation:** https://gethomepage.dev/en/installation/
- **Widgets Guide:** https://gethomepage.dev/en/widgets/
- **Service Integrations:** https://gethomepage.dev/en/widgets/services/
- **Discord:** https://discord.gg/k4ruYNrudu
## Educational Resources
### Videos
- [Homepage - The BEST Homelab Dashboard (Techno Tim)](https://www.youtube.com/watch?v=_MxpGN8eS4U)
- [Homepage Setup Guide (DB Tech)](https://www.youtube.com/watch?v=N9dQKJMrjZM)
- [Homepage vs Homarr vs Heimdall](https://www.youtube.com/results?search_query=homepage+vs+homarr)
- [Customizing Homepage Dashboard](https://www.youtube.com/results?search_query=homepage+dashboard+customization)
### Articles & Guides
- [Homepage Official Documentation](https://gethomepage.dev)
- [Service Widget Configuration](https://gethomepage.dev/en/widgets/services/)
- [Docker Integration Guide](https://gethomepage.dev/en/configs/docker/)
- [Customization Tips](https://gethomepage.dev/en/configs/custom-css-js/)
### Concepts to Learn
- **YAML Configuration:** Structured data format
- **API Integration:** RESTful service communication
- **Health Checks:** Service availability monitoring
- **Widgets:** Modular dashboard components
- **Docker Labels:** Metadata for auto-discovery
- **Reverse Proxy:** Accessing services through dashboard
## Docker Configuration
### Complete Service Definition
```yaml
homepage:
image: ghcr.io/gethomepage/homepage:latest
container_name: homepage
restart: unless-stopped
networks:
- traefik-network
ports:
- "3000:3000"
volumes:
- /opt/stacks/dashboards/homepage/config:/app/config
- /var/run/docker.sock:/var/run/docker.sock:ro # For Docker integration
environment:
- PUID=1000
- PGID=1000
- TZ=America/New_York
labels:
- "traefik.enable=true"
- "traefik.http.routers.homepage.rule=Host(`${DOMAIN}`) || Host(`homepage.${DOMAIN}`)"
- "traefik.http.routers.homepage.entrypoints=websecure"
- "traefik.http.routers.homepage.tls.certresolver=letsencrypt"
- "traefik.http.services.homepage.loadbalancer.server.port=3000"
```
## Configuration Guide
### settings.yaml
```yaml
---
# Global settings
title: My Homelab
background: /images/background.jpg # Optional
cardBlur: md # sm, md, lg
theme: dark # dark, light, auto
color: slate # slate, gray, zinc, neutral, stone, red, etc.
# Layout
layout:
Media:
style: row
columns: 4
Infrastructure:
style: row
columns: 3
# Quick search
quicklaunch:
searchDescriptions: true
hideInternetSearch: true
# Header widgets (shown at top)
headerStyle: clean # boxed, clean
```
### services.yaml
```yaml
---
# Service groups and cards
- Media:
- Plex:
icon: plex.png
href: https://plex.yourdomain.com
description: Media Server
widget:
type: plex
url: http://plex:32400
key: your-plex-token
- Sonarr:
icon: sonarr.png
href: https://sonarr.yourdomain.com
description: TV Show Management
widget:
type: sonarr
url: http://sonarr:8989
key: your-sonarr-api-key
- Radarr:
icon: radarr.png
href: https://radarr.yourdomain.com
description: Movie Management
widget:
type: radarr
url: http://radarr:7878
key: your-radarr-api-key
- qBittorrent:
icon: qbittorrent.png
href: https://qbit.yourdomain.com
description: Torrent Client
widget:
type: qbittorrent
url: http://gluetun:8080
username: admin
password: adminpass
- Infrastructure:
- Dockge:
icon: dockge.png
href: https://dockge.yourdomain.com
description: Stack Manager
- Portainer:
icon: portainer.png
href: https://portainer.yourdomain.com
description: Docker Management
- Traefik:
icon: traefik.png
href: https://traefik.yourdomain.com
description: Reverse Proxy
widget:
type: traefik
url: http://traefik:8080
- Monitoring:
- Glances:
icon: glances.png
href: https://glances.yourdomain.com
description: System Monitor
widget:
type: glances
url: http://glances:61208
- Uptime Kuma:
icon: uptime-kuma.png
href: https://uptime.yourdomain.com
description: Uptime Monitor
```
### widgets.yaml
```yaml
---
# Dashboard widgets (shown above services)
- logo:
icon: /icons/logo.png # Optional custom logo
- search:
provider: google
target: _blank
- datetime:
text_size: xl
format:
timeStyle: short
dateStyle: short
- resources:
cpu: true
memory: true
disk: /
cputemp: true
uptime: true
label: Server
- openmeteo:
label: Home
latitude: 40.7128
longitude: -74.0060
units: imperial
cache: 5
- greeting:
text_size: xl
text: Welcome to my Homelab!
```
### bookmarks.yaml
```yaml
---
# Quick links and bookmarks
- Developer:
- GitHub:
- icon: github.png
href: https://github.com
- GitLab:
- icon: gitlab.png
href: https://gitlab.com
- Documentation:
- Homepage Docs:
- icon: homepage.png
href: https://gethomepage.dev
- Docker Docs:
- icon: docker.png
href: https://docs.docker.com
- Social:
- Reddit:
- icon: reddit.png
href: https://reddit.com/r/homelab
- Discord:
- icon: discord.png
href: https://discord.gg/homelab
```
### docker.yaml
```yaml
---
# Auto-discover Docker containers
my-docker:
host: docker-proxy # Use socket proxy for security
port: 2375
# Or direct socket (less secure):
# socket: /var/run/docker.sock
```
Then add to services.yaml:
```yaml
- Docker:
- My Container:
icon: docker.png
description: Auto-discovered container
server: my-docker
container: container-name
```
## Widgets and Integrations
### Service Widgets
**Popular Integrations:**
**Plex:**
```yaml
widget:
type: plex
url: http://plex:32400
key: your-plex-token # Get from Plex Web → Settings → Network → Show Advanced
```
**Sonarr/Radarr:**
```yaml
widget:
type: sonarr
url: http://sonarr:8989
key: your-api-key # Settings → General → API Key
```
**qBittorrent:**
```yaml
widget:
type: qbittorrent
url: http://gluetun:8080
username: admin
password: adminpass
```
**Pi-hole:**
```yaml
widget:
type: pihole
url: http://pihole:80
key: your-api-key # Settings → API → Show API token
```
**Traefik:**
```yaml
widget:
type: traefik
url: http://traefik:8080
```
**AdGuard Home:**
```yaml
widget:
type: adguard
url: http://adguard:80
username: admin
password: adminpass
```
### Information Widgets
**Weather:**
```yaml
- openmeteo:
label: Home
latitude: 40.7128
longitude: -74.0060
units: imperial # or metric
cache: 5
```
**System Resources:**
```yaml
- resources:
cpu: true
memory: true
disk: /
cputemp: true
uptime: true
label: Server
```
**Docker Stats:**
```yaml
- docker:
server: my-docker
show: running # or all
```
**Glances:**
```yaml
- glances:
url: http://glances:61208
cpu: true
mem: true
process: true
```
### Custom Widgets
```yaml
- customapi:
url: http://myapi.local/endpoint
refreshInterval: 60000 # 60 seconds
display: text # or list, block
mappings:
- field: data.value
label: My Value
format: text
```
## Advanced Topics
### Custom CSS
Create `/config/custom.css`:
```css
/* Custom background */
body {
background-image: url('/images/custom-bg.jpg');
background-size: cover;
}
/* Larger service cards */
.service-card {
min-height: 150px;
}
/* Custom colors */
:root {
--color-primary: #1e40af;
--color-secondary: #7c3aed;
}
/* Hide specific elements */
.some-class {
display: none;
}
```
### Custom JavaScript
Create `/config/custom.js`:
```javascript
// Custom functionality
console.log('Homepage loaded!');
// Example: Auto-refresh every 5 minutes
setTimeout(() => {
window.location.reload();
}, 300000);
```
### Multi-Column Layouts
```yaml
layout:
Media:
style: row
columns: 4
Infrastructure:
style: column
columns: 2
Monitoring:
style: row
columns: 3
```
### Custom Icons
Place icons in `/config/icons/`:
```
/config/icons/
├── custom-icon1.png
├── custom-icon2.svg
└── custom-icon3.jpg
```
Reference in services:
```yaml
- My Service:
icon: /icons/custom-icon1.png
```
### Docker Auto-Discovery
Automatically add containers with labels:
```yaml
# In container compose file
my-service:
labels:
- "homepage.group=Media"
- "homepage.name=My Service"
- "homepage.icon=service-icon.png"
- "homepage.href=https://service.domain.com"
- "homepage.description=My awesome service"
```
### Ping Health Checks
```yaml
- My Service:
icon: service.png
href: https://service.domain.com
ping: https://service.domain.com
# Shows green/red status indicator
```
### Custom API Widgets
```yaml
- customapi:
url: http://api.local/stats
refreshInterval: 30000
display: block
mappings:
- field: users
label: Active Users
format: number
- field: status
label: Status
format: text
```
## Troubleshooting
### Homepage Not Loading
```bash
# Check if container is running
docker ps | grep homepage
# View logs
docker logs homepage
# Check port
curl http://localhost:3000
# Verify Traefik routing
docker logs traefik | grep homepage
```
### Service Widgets Not Showing Data
```bash
# Check API connectivity
docker exec homepage curl http://service:port
# Verify API key is correct
# Check service logs for auth errors
# Test API manually
curl -H "X-Api-Key: your-key" http://service:port/api/endpoint
# Check Homepage logs for errors
docker logs homepage | grep -i error
```
### Configuration Changes Not Applied
```bash
# Homepage auto-reloads config files
# Wait 10-20 seconds
# Or restart container
docker restart homepage
# Check YAML syntax
# Use online YAML validator
# View Homepage logs
docker logs homepage | grep -i config
```
### Docker Socket Permission Error
```bash
# Fix socket permissions
sudo chmod 666 /var/run/docker.sock
# Or use Docker Socket Proxy (recommended)
# See docker-proxy.md
# Check mount
docker inspect homepage | grep -A5 Mounts
```
### Icons Not Displaying
```bash
# Homepage uses icon CDN by default
# Check internet connectivity
# Use local icons instead
# Place in /config/icons/
# Clear browser cache
# Hard refresh: Ctrl+Shift+R
# Check icon name matches service
# List available icons: https://github.com/walkxcode/dashboard-icons
```
### High CPU/Memory Usage
```bash
# Check container stats
docker stats homepage
# Reduce API polling frequency
# In services.yaml, add cache settings
# Disable unnecessary widgets
# Check for network issues
docker logs homepage | grep timeout
```
## Performance Optimization
### Reduce API Calls
```yaml
# Increase refresh intervals
widget:
type: sonarr
url: http://sonarr:8989
key: api-key
refreshInterval: 300000 # 5 minutes instead of default 10 seconds
```
### Cache Configuration
```yaml
# In settings.yaml
cache:
size: 100 # Number of cached responses
ttl: 300 # Cache time in seconds
```
### Lazy Loading
```yaml
# In settings.yaml
lazyLoad: true # Load images as they scroll into view
```
## Customization Tips
### Color Themes
Available colors: `slate`, `gray`, `zinc`, `neutral`, `stone`, `red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`
```yaml
color: blue
theme: dark
```
### Background Images
```yaml
background: /images/my-background.jpg
backgroundBlur: sm # sm, md, lg, xl
backgroundSaturate: 50 # 0-100
backgroundBrightness: 50 # 0-100
```
### Card Appearance
```yaml
cardBlur: md # sm, md, lg, xl
hideVersion: true
showStats: true
```
### Custom Greeting
```yaml
- greeting:
text_size: xl
text: "Welcome back, {{name}}!"
```
## Integration Examples
### Complete Media Stack
```yaml
- Media Server:
- Plex:
icon: plex.png
href: https://plex.domain.com
widget:
type: plex
url: http://plex:32400
key: token
- Jellyfin:
icon: jellyfin.png
href: https://jellyfin.domain.com
widget:
type: jellyfin
url: http://jellyfin:8096
key: api-key
- Media Management:
- Sonarr:
icon: sonarr.png
href: https://sonarr.domain.com
widget:
type: sonarr
url: http://sonarr:8989
key: api-key
- Radarr:
icon: radarr.png
href: https://radarr.domain.com
widget:
type: radarr
url: http://radarr:7878
key: api-key
- Prowlarr:
icon: prowlarr.png
href: https://prowlarr.domain.com
widget:
type: prowlarr
url: http://prowlarr:9696
key: api-key
```
## Summary
Homepage provides a beautiful, functional dashboard for your homelab. It offers:
- Clean, modern interface
- Real-time service monitoring
- API integrations for live data
- Easy YAML configuration
- Highly customizable
- Active development and community
**Perfect for:**
- Homelab landing page
- Service overview
- Quick access portal
- Status monitoring
- Aesthetic presentation
**Best Practices:**
- Use Authelia for authentication if exposed
- Configure API widgets for live data
- Organize services into logical groups
- Use custom icons for consistency
- Enable Docker integration for automation
- Regular config backups
- Keep updated for new features
**Remember:**
- YAML syntax matters (indentation!)
- Test API connections before configuring widgets
- Use Docker Socket Proxy for security
- Customize colors and themes to preference
- Start simple, add complexity gradually
- Homepage is your homelab's front door - make it welcoming!