homelab/compose/services/homarr/README.md

Homarr Dashboard

Modern, customizable dashboard with automatic Docker service discovery.

Features

• 🎨 Modern UI - Beautiful, responsive design
• 🔍 Auto-Discovery - Automatically finds Docker services
• 📊 Widgets - System stats, weather, calendar, RSS, etc.
• 🏷️ Labels - Organize services by category
• 🔗 Integration - Connects to *arr apps, Jellyfin, etc.
• 🎯 Customizable - Drag-and-drop layout
• 🌙 Dark Mode - Built-in dark theme
• 📱 Mobile Friendly - Works on all devices

Access

• URL: https://home.fig.systems or https://home.edfig.dev
• Port: 7575 (if accessing directly)

First-Time Setup

1. Deploy Homarr

cd compose/services/homarr
docker compose up -d

2. Access Dashboard

Open https://home.fig.systems in your browser.

3. Auto-Discovery

Homarr will automatically detect services with these labels:

labels:
  homarr.name: "Service Name"
  homarr.group: "Category"
  homarr.icon: "/icons/service.png"
  homarr.href: "https://service.fig.systems"

Adding Services to Dashboard

Automatic (Recommended)

Add labels to your service's compose.yaml:

labels:
  # Traefik labels...
  traefik.enable: true
  # ... etc

  # Homarr labels
  homarr.name: Jellyfin
  homarr.group: Media
  homarr.icon: https://cdn.jsdelivr.net/gh/walkxcode/dashboard-icons/png/jellyfin.png
  homarr.href: https://flix.fig.systems

Redeploy the service:

docker compose up -d

Homarr will automatically add it to the dashboard!

Manual

1. Click the "+" button in Homarr
2. Select "Add Service"
3. Fill in:
   • Name: Service name
   • URL: https://service.fig.systems
   • Icon: Choose from library or custom URL
   • Category: Group services (Media, Services, etc.)

Integration with Services

Jellyfin

Add to Jellyfin's compose.yaml:

labels:
  homarr.name: Jellyfin
  homarr.group: Media
  homarr.icon: /icons/jellyfin.png
  homarr.widget.type: jellyfin
  homarr.widget.url: http://jellyfin:8096
  homarr.widget.key: ${JELLYFIN_API_KEY}

Shows: Currently playing, library stats

Sonarr/Radarr

labels:
  homarr.name: Sonarr
  homarr.group: Media Automation
  homarr.icon: /icons/sonarr.png
  homarr.widget.type: sonarr
  homarr.widget.url: http://sonarr:8989
  homarr.widget.key: ${SONARR_API_KEY}

Shows: Queue, calendar, missing episodes

qBittorrent

labels:
  homarr.name: qBittorrent
  homarr.group: Downloads
  homarr.icon: /icons/qbittorrent.png
  homarr.widget.type: qbittorrent
  homarr.widget.url: http://qbittorrent:8080
  homarr.widget.username: ${QBIT_USERNAME}
  homarr.widget.password: ${QBIT_PASSWORD}

Shows: Active torrents, download speed

Available Widgets

System Monitoring

• CPU Usage - Real-time CPU stats
• Memory Usage - RAM usage
• Disk Space - Storage capacity
• Network - Upload/download speeds

Services

• Jellyfin - Media server stats
• Sonarr - TV show automation
• Radarr - Movie automation
• Lidarr - Music automation
• Readarr - Book automation
• Prowlarr - Indexer management
• SABnzbd - Usenet downloads
• qBittorrent - Torrent downloads
• Overseerr/Jellyseerr - Media requests

Utilities

• Weather - Local weather forecast
• Calendar - Events and tasks
• RSS Feeds - News aggregator
• Docker - Container status
• Speed Test - Internet speed
• Notes - Sticky notes
• Iframe - Embed any website

Customization

Change Theme

1. Click settings icon (⚙️)
2. Go to "Appearance"
3. Choose color scheme
4. Save

Reorganize Layout

1. Click edit mode (✏️)
2. Drag and drop services
3. Resize widgets
4. Click save

Add Categories

1. Click "Add Category"
2. Name it (e.g., "Media", "Tools", "Infrastructure")
3. Drag services into categories
4. Collapse/expand as needed

Custom Icons

Option 1: Use Icon Library

• Homarr includes icons from Dashboard Icons
• Search by service name

Option 2: Custom URL

https://cdn.jsdelivr.net/gh/walkxcode/dashboard-icons/png/service.png

Option 3: Local Icons

• Place in ./icons/ directory
• Reference as /icons/service.png

Recommended Dashboard Layout

┌─────────────────────────────────────────┐
│          🏠 Homelab Dashboard           │
├─────────────────────────────────────────┤
│  [System Stats] [Weather] [Calendar]    │
├─────────────────────────────────────────┤
│  📺 Media                               │
│  [Jellyfin] [Jellyseerr] [Immich]      │
├─────────────────────────────────────────┤
│  🤖 Media Automation                    │
│  [Sonarr] [Radarr] [qBittorrent]       │
├─────────────────────────────────────────┤
│  🛠️ Services                             │
│  [Linkwarden] [Vikunja] [FreshRSS]     │
├─────────────────────────────────────────┤
│  🔧 Infrastructure                      │
│  [Traefik] [LLDAP] [Tinyauth]          │
└─────────────────────────────────────────┘

Add to All Services

To make all your services auto-discoverable, add these labels:

Jellyfin

homarr.name: Jellyfin
homarr.group: Media
homarr.icon: https://cdn.jsdelivr.net/gh/walkxcode/dashboard-icons/png/jellyfin.png

Jellyseerr

homarr.name: Jellyseerr
homarr.group: Media
homarr.icon: https://cdn.jsdelivr.net/gh/walkxcode/dashboard-icons/png/jellyseerr.png

Immich

homarr.name: Immich Photos
homarr.group: Media
homarr.icon: https://cdn.jsdelivr.net/gh/walkxcode/dashboard-icons/png/immich.png

Sonarr/Radarr/SABnzbd/qBittorrent

homarr.name: [Service]
homarr.group: Automation
homarr.icon: https://cdn.jsdelivr.net/gh/walkxcode/dashboard-icons/png/[service].png

Linkwarden/Vikunja/etc.

homarr.name: [Service]
homarr.group: Utilities
homarr.icon: https://cdn.jsdelivr.net/gh/walkxcode/dashboard-icons/png/[service].png

Mobile Access

Homarr is fully responsive. For best mobile experience:

1. Add to home screen (iOS/Android)
2. Works as PWA (Progressive Web App)
3. Touch-optimized interface

Backup Configuration

Backup

cd compose/services/homarr
tar -czf homarr-backup-$(date +%Y%m%d).tar.gz config/ data/

Restore

cd compose/services/homarr
tar -xzf homarr-backup-YYYYMMDD.tar.gz
docker compose restart

Troubleshooting

Services not auto-discovered

Check Docker socket permission:

docker logs homarr

Verify labels on service:

docker inspect service-name | grep homarr

Can't connect to services

Services must be on same Docker network or accessible via hostname.

Use container names, not localhost:

• ✅ http://jellyfin:8096
• ❌ http://localhost:8096

Widgets not working

1. Check API keys are correct
2. Verify service URLs (use container names)
3. Check service is running: docker ps

Alternatives Considered

Dashboard	Auto-Discovery	Widgets	Complexity
Homarr	✅ Excellent	✅ Many	Low
Homepage	✅ Good	✅ Many	Low
Heimdall	❌ Manual	❌ Few	Very Low
Dashy	⚠️ Limited	✅ Some	Medium
Homer	❌ Manual	❌ None	Very Low
Organizr	⚠️ Limited	✅ Many	High

Homarr chosen for: Best balance of features, auto-discovery, and ease of use.

Resources

• Official Docs
• GitHub
• Discord Community
• Icon Library

Tips

1. Start Simple - Add core services first, expand later
2. Use Categories - Group related services
3. Enable Widgets - Make dashboard informative
4. Mobile First - Test on phone/tablet
5. Backup Config - Save your layout regularly