EZ-Homelab/docs/service-docs/homarr.md

Homarr - Another Application Dashboard

Table of Contents

• Overview
• What is Homarr?
• Why Use Homarr?
• How It Works
• Configuration in AI-Homelab
• Official Resources
• Educational Resources
• Docker Configuration
• Setup and Usage
• Widgets and Apps
• Advanced Topics
• Troubleshooting

Overview

Category: Dashboard
Docker Image: ghcr.io/ajnart/homarr
Default Stack: dashboards.yml
Web UI: https://homarr.${DOMAIN} or http://SERVER_IP:7575
Authentication: Built-in user system
Purpose: Interactive application dashboard (alternative to Homepage)

What is Homarr?

Homarr is a customizable application dashboard with a focus on ease of use and interactivity. Unlike Homepage's YAML configuration, Homarr offers a web-based drag-and-drop interface for building your dashboard.

Key Features

• Drag-and-Drop UI: Visual dashboard builder
• Built-in Auth: User accounts and permissions
• App Integrations: 50+ service widgets
• Custom Widgets: RSS, Calendar, Weather, Docker stats
• Responsive Design: Mobile-friendly
• Multi-Board Support: Create multiple dashboards
• Search Integration: Built-in search aggregation
• Docker Integration: Container status monitoring
• Customizable Themes: Light/dark mode with colors
• Widget Variety: Information, media, monitoring widgets
• No Configuration Files: Everything managed via GUI
• Modern UI: Clean, intuitive interface

Why Use Homarr?

Homarr vs Homepage

Use Homarr if you want:

• ✅ GUI-based configuration (no YAML)
• ✅ Drag-and-drop dashboard building
• ✅ Built-in user authentication
• ✅ Interactive widget management
• ✅ Visual customization
• ✅ More widget variety
• ✅ Easier for non-technical users

Use Homepage if you want:

• ✅ YAML configuration (GitOps friendly)
• ✅ Lighter resource usage
• ✅ Faster performance
• ✅ More mature project
• ✅ Configuration as code

Common Use Cases

1. Family Dashboard: Easy for non-technical users
2. Media Center: Integrated media widgets
3. Multiple Dashboards: Different boards for different purposes
4. Interactive Monitoring: Clickable, actionable widgets
5. Visual Customization: Design your perfect dashboard

How It Works

User → Browser → Homarr Web UI
                      ↓
              Dashboard Editor
            (Drag-and-drop interface)
                      ↓
         ┌────────────┴────────────┐
         ↓                         ↓
    App Tiles                  Widgets
    (Services)           (Live data, RSS, etc.)
         ↓                         ↓
    Click to access        API integrations
    service                (Sonarr, Radarr, etc.)

Architecture

Data Storage:

• SQLite database (stores dashboards, users, settings)
• Configuration directory (icons, backups)
• No YAML files required

Components:

1. Web Interface: Dashboard builder and viewer
2. API Backend: Service integrations
3. Database: User accounts, dashboards, settings
4. Docker Integration: Container monitoring

Configuration in AI-Homelab

Directory Structure

/opt/stacks/dashboards/homarr/
├── data/           # Database and configs
├── icons/          # Custom icons
└── backups/        # Dashboard backups

Environment Variables

# Base URL (if behind reverse proxy)
BASE_URL=https://homarr.yourdomain.com

# Port
PORT=7575

# Timezone
TZ=America/New_York

# Optional: Disable analytics
DISABLE_ANALYTICS=true

Official Resources

• Website: https://homarr.dev
• GitHub: https://github.com/ajnart/homarr
• Documentation: https://homarr.dev/docs/introduction
• Discord: https://discord.gg/aCsmEV5RgA
• Demo: https://demo.homarr.dev

Educational Resources

Videos

• Homarr - Modern Dashboard for Your Homelab (Techno Tim)
• Homarr Setup Tutorial (DB Tech)
• Homepage vs Homarr - Which Dashboard?

Articles & Guides

• Homarr Official Documentation
• Widget Configuration Guide
• Integration Setup

Concepts to Learn

• Dashboard Builders: Visual interface design
• Widget Systems: Modular dashboard components
• API Integration: Service data fetching
• User Authentication: Multi-user support
• Docker Integration: Container monitoring
• Responsive Design: Mobile-friendly layouts

Docker Configuration

Complete Service Definition

homarr:
  image: ghcr.io/ajnart/homarr:latest
  container_name: homarr
  restart: unless-stopped
  networks:
    - traefik-network
  ports:
    - "7575:7575"
  volumes:
    - /opt/stacks/dashboards/homarr/data:/app/data/configs
    - /opt/stacks/dashboards/homarr/icons:/app/public/icons
    - /opt/stacks/dashboards/homarr/data:/data
    - /var/run/docker.sock:/var/run/docker.sock:ro  # For Docker integration
  environment:
    - BASE_URL=https://homarr.${DOMAIN}
    - PORT=7575
    - TZ=America/New_York
    - DISABLE_ANALYTICS=true
  labels:
    - "traefik.enable=true"
    - "traefik.http.routers.homarr.rule=Host(`homarr.${DOMAIN}`)"
    - "traefik.http.routers.homarr.entrypoints=websecure"
    - "traefik.http.routers.homarr.tls.certresolver=letsencrypt"
    - "traefik.http.services.homarr.loadbalancer.server.port=7575"

Setup and Usage

Initial Setup

1. Access Homarr:

   • Navigate to: https://homarr.yourdomain.com
   • Or: http://SERVER_IP:7575

2. Create Admin Account:

   • Click "Get Started"
   • Enter username and password
   • Create first dashboard

3. Dashboard Creation:

   • Name your dashboard
   • Choose layout (grid, list, etc.)
   • Start adding apps and widgets

Adding Applications

Method 1: Manual Add

1. Click "Edit Mode" (pencil icon)
2. Click "+" button
3. Select "App"
4. Fill in details:
   • Name
   • URL
   • Icon (search or upload)
   • Description
5. Save

Method 2: Integration

1. Add app as above
2. Click "Integration" tab
3. Select service type (Sonarr, Radarr, etc.)
4. Enter API URL and key
5. Save - widget will show live data

Method 3: Docker Discovery

1. Enable Docker integration
2. Homarr auto-discovers containers
3. Add discovered apps to dashboard

Dashboard Editor

Edit Mode:

• Click pencil icon to enter edit mode
• Drag tiles to rearrange
• Resize tiles by dragging corners
• Delete tiles with X button
• Click tiles to edit settings

Grid System:

• Tiles snap to grid
• Customizable grid size
• Responsive layout
• Mobile-optimized views

Categories:

• Create sections (Media, Management, etc.)
• Collapse/expand categories
• Organize apps logically

User Management

Create Users:

1. Settings → Users → Add User
2. Set username and password
3. Assign permissions
4. User can login and customize their dashboard

Permissions:

• Admin: Full access
• User: View and edit own dashboards
• Guest: Read-only access

Widgets and Apps

Application Widgets

Supported Integrations:

Media:

• Plex, Jellyfin, Emby
• Sonarr, Radarr, Lidarr, Readarr
• Prowlarr, Jackett
• qBittorrent, Transmission, Deluge
• Tautulli (Plex stats)
• Overseerr, Jellyseerr

Infrastructure:

• Portainer
• Traefik
• Pi-hole, AdGuard Home
• Uptime Kuma
• Proxmox

Other:

• Home Assistant
• Nextcloud
• Gitea
• Calibre-Web
• Many more...

Information Widgets

Weather Widget:

Location: Auto-detect or manual
Provider: OpenWeatherMap, WeatherAPI
Units: Imperial/Metric
Forecast: 3-7 days

Calendar Widget:

Type: iCal URL
Source: Google Calendar, Nextcloud, etc.
Events: Upcoming events display

RSS Widget:

Feed URL: Any RSS/Atom feed
Items: Number to show
Refresh: Update interval

Docker Widget:

Shows: Running/Stopped containers
Stats: CPU, Memory, Network
Control: Start/Stop containers (if permissions)

Clock Widget:

Format: 12h/24h
Timezone: Custom or system
Date: Show/hide
Analog/Digital: Style choice

Media Server Widget:

Plex/Jellyfin: Currently playing
Recent: Recently added
Stats: Library counts

Custom Widgets

HTML Widget:

• Embed custom HTML
• Use for iframes, custom content
• CSS styling support

Iframe Widget:

• Embed external websites
• Dashboard within dashboard
• Useful for Grafana, etc.

Image Widget:

• Display static images
• Backgrounds, logos
• Network/local images

Advanced Topics

Custom Icons

Upload Custom Icons:

1. Place icons in /icons/ directory
2. Or upload via UI
3. Reference in app settings

Icon Sources:

• Built-in icon library (1000+)
• Upload your own (PNG, SVG, JPG)
• URL to external icon
• Dashboard Icons repository

Multiple Dashboards

Create Multiple Boards:

1. Settings → Boards → New Board
2. Name and configure
3. Switch between boards
4. Different dashboards for different purposes:
   • Family board
   • Admin board
   • Media board
   • etc.

Board Sharing:

• Share board link
• Set access permissions
• Public vs private boards

Themes and Customization

Theme Options:

• Light/Dark mode
• Accent colors
• Background images
• Custom CSS (advanced)

Layout Options:

• Grid size
• Tile spacing
• Column count
• Responsive breakpoints

Docker Integration

Enable Docker:

1. Mount Docker socket
2. Settings → Docker → Enable
3. Select which containers to show
4. Auto-discovery or manual

Docker Features:

• Container status
• Start/Stop controls (if enabled)
• Resource usage
• Quick access to logs

API Access

REST API:

• Endpoint: https://homarr.domain.com/api
• Authentication: API key
• Use for automation
• Integration with other tools

API Uses:

• Automated dashboard updates
• External monitoring
• Custom integrations
• Backup automation

Backup and Restore

Manual Backup:

1. Settings → Backups
2. Create backup
3. Download JSON file

Restore:

1. Settings → Backups
2. Upload backup file
3. Select boards to restore

File System Backup:

# Backup entire data directory
tar -czf homarr-backup-$(date +%Y%m%d).tar.gz /opt/stacks/dashboards/homarr/data/

# Restore
tar -xzf homarr-backup-20240112.tar.gz -C /opt/stacks/dashboards/homarr/
docker restart homarr

Import/Export

Export Dashboard:

• Settings → Export → Download JSON
• Share with others
• Version control

Import Dashboard:

• Settings → Import → Upload JSON
• Community dashboards
• Template boards

Troubleshooting

Homarr Not Loading

# Check container status
docker ps | grep homarr

# View logs
docker logs homarr

# Test port
curl http://localhost:7575

# Check Traefik routing
docker logs traefik | grep homarr

Can't Login

# Reset admin password
docker exec -it homarr npm run db:reset-password

# Or recreate database (WARNING: loses data)
docker stop homarr
rm -rf /opt/stacks/dashboards/homarr/data/db.sqlite
docker start homarr
# Creates new database, need to setup again

Widgets Not Showing Data

# Check API connectivity
docker exec homarr curl http://service:port

# Verify API key
# Re-enter in widget settings

# Check service logs
docker logs service-name

# Test API manually
curl -H "X-Api-Key: key" http://service:port/api/endpoint

Icons Not Displaying

# Clear browser cache
# Ctrl+Shift+R (hard refresh)

# Check icon path
ls -la /opt/stacks/dashboards/homarr/icons/

# Ensure proper permissions
sudo chown -R 1000:1000 /opt/stacks/dashboards/homarr/

# Re-upload icon via UI

Docker Integration Not Working

# Verify socket mount
docker inspect homarr | grep -A5 Mounts

# Check socket permissions
ls -la /var/run/docker.sock

# Fix permissions
sudo chmod 666 /var/run/docker.sock

# Or use Docker Socket Proxy (recommended)

High Memory Usage

# Check container stats
docker stats homarr

# Typical usage: 100-300MB
# If higher, restart container
docker restart homarr

# Reduce widgets if needed
# Remove unused integrations

Slow Performance

# Reduce widget refresh rates
# Edit widget → Change refresh interval

# Disable unused features
# Settings → Integrations → Disable unused

# Check network latency
# Ping services from Homarr container

# Restart container
docker restart homarr

Performance Optimization

Reduce API Calls

• Increase widget refresh intervals
• Disable widgets for services you don't monitor frequently
• Use lazy loading for images

Optimize Docker

homarr:
  deploy:
    resources:
      limits:
        cpus: '1.0'
        memory: 512M
      reservations:
        memory: 128M

Cache Settings

• Enable browser caching
• Use CDN for icons if available
• Optimize image sizes

Comparison with Alternatives

Homarr vs Homepage

Homarr:

• GUI configuration
• Built-in authentication
• Drag-and-drop
• More interactive
• Higher resource usage

Homepage:

• YAML configuration
• External auth required
• Faster performance
• GitOps friendly
• Lighter weight

Homarr vs Heimdall

Homarr:

• More modern UI
• Better integrations
• Active development
• More features

Heimdall:

• Simpler
• Very lightweight
• Established project
• Basic functionality

Homarr vs Organizr

Homarr:

• Newer, modern
• Better mobile support
• Easier setup
• More widgets

Organizr:

• More mature
• Tab-based interface
• Different philosophy
• Large community

Tips and Tricks

Efficient Layouts

Media Dashboard:

• Large tiles for Plex/Jellyfin
• Medium tiles for *arr apps
• Small tiles for indexers
• Weather widget in corner

Admin Dashboard:

• Grid of management tools
• Docker status widget
• System resource widget
• Recent logs/alerts

Family Dashboard:

• Large, simple icons
• Hide technical services
• Focus on media/content
• Bright, friendly theme

Widget Combinations

Media Setup:

1. Plex/Jellyfin (large, with integration)
2. Sonarr/Radarr (medium, with stats)
3. qBittorrent (small, with speed)
4. Recently added (widget)

Monitoring Setup:

1. Docker widget (container status)
2. Pi-hole widget (blocking stats)
3. Uptime Kuma widget (service status)
4. Weather widget (why not?)

Custom Styling

Use custom CSS for unique looks:

• Rounded corners
• Custom colors
• Transparency effects
• Animations

Summary

Homarr is a user-friendly, interactive dashboard that offers:

• Visual dashboard builder
• Built-in authentication
• Rich widget ecosystem
• Drag-and-drop interface
• Modern, responsive design
• No configuration files needed

Perfect for:

• Users who prefer GUI over YAML
• Multi-user environments
• Interactive dashboards
• Visual customization fans
• Quick setup without learning curve

Trade-offs:

• Higher resource usage than Homepage
• Database dependency
• Less GitOps friendly
• Newer project (less mature)

Best Practices:

• Use both Homepage and Homarr (they complement each other)
• Homepage for you, Homarr for family
• Regular backups of database
• Optimize widget refresh rates
• Use Docker Socket Proxy for security
• Keep updated for new features

Remember:

• Homarr is all about visual customization
• No YAML - everything in UI
• Great for non-technical users
• Built-in auth is convenient
• Can coexist with Homepage
• Choose based on your preference and use case