Homarr: Beautiful Dashboard with Advanced Management

Overview

Homarr is a modern, sleek dashboard that goes beyond simple bookmarks to become your homelab’s central command center. With built-in Docker integration, service health monitoring, media management widgets, and a customizable widget system, Homarr combines the aesthetics of modern web apps with the functionality homelabbers actually need.

Unlike basic homepage applications, Homarr actively monitors your services, integrates with your Docker containers, displays real-time stats, and provides actionable controls—all while looking beautiful on any device from your phone to your 4K monitor.

What you’ll learn:

Installing Homarr with Docker Compose
Creating and organizing service tiles
Configuring widgets (weather, calendar, media, Docker stats)
Integrating with popular homelab services (Sonarr, Radarr, Jellyfin, etc.)
Docker container management from the dashboard
Customizing themes and layouts
Setting up authentication and user accounts
Advanced features: custom CSS, API integration, automation

Why Homarr for Your Homelab?

Instead of bookmarks spread across browser tabs or a static HTML page, Homarr gives you live status indicators, one-click service access, Docker container controls, download progress bars for your media stack, upcoming calendar events, and real-time server stats—all in one elegant interface.

Prerequisites

Before starting, ensure you have:

Docker and Docker Compose installed
Basic web browser (modern browser required for best experience)
Hardware requirements:
- 512 MB RAM minimum
- 1 GB storage
- Network: Port 7575 (customizable)
Optional homelab services to integrate (Sonarr, Radarr, Jellyfin, etc.)

Optional but enhances experience:

Reverse proxy (for HTTPS and custom domain)
Docker containers running on the same host
API keys for integrated services

Understanding Homarr’s Philosophy

What Makes Homarr Different

Homepage/Dashy:

Static links and bookmarks
Manual service status checks
Limited interactivity

Homarr:

Live service monitoring
Docker container management
Interactive widgets
Beautiful, responsive design
Built-in integrations

Core Features

Service Tiles:

Quick access links to your services
Automatic ping-based health checks
Custom icons (local or icon libraries)
Grouping and categorization
Search functionality

Docker Integration:

View running containers
Start/stop/restart containers
Container resource usage
Quick container logs access

Widgets:

Weather: Current conditions and forecast
Calendar: Display upcoming events
Media: Sonarr/Radarr queue and activity
System Stats: CPU, RAM, storage usage
Custom: Create your own widgets

Customization:

Multiple themes (light/dark/custom)
Grid layout configuration
Custom CSS support
Per-user dashboards
Mobile-responsive design

Installation with Docker Compose

Basic Installation

Create docker-compose.yml:

version: '3.8'

services:
  homarr:
    container_name: homarr
    image: ghcr.io/ajnart/homarr:latest
    restart: unless-stopped
    ports:
      - '7575:7575'
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro  # Optional: for Docker integration
      - ./homarr/configs:/app/data/configs
      - ./homarr/icons:/app/public/icons
      - ./homarr/data:/data
    environment:
      - TZ=America/New_York
      - PUID=1000
      - PGID=1000

Deploy:

# Create directory
mkdir -p ~/homarr && cd ~/homarr

# Create docker-compose.yml (above)
nano docker-compose.yml

# Create data directories
mkdir -p homarr/{configs,icons,data}

# Start Homarr
docker-compose up -d

# Check logs
docker-compose logs -f homarr

Access Homarr:

Navigate to http://localhost:7575 or http://YOUR-SERVER-IP:7575

First-Time Setup

1. Welcome screen:

Choose default layout (grid recommended)
Select theme preference
Click Continue

2. Create admin account:

Username: your-username
Password: create strong password
Confirm password
Click Create Account

3. Initial dashboard:

Empty dashboard with edit mode enabled
Ready to add services and widgets

Creating Service Tiles

Adding Your First Service

1. Click “Edit Mode” (pencil icon top-right)

2. Click “Add a Service”

3. Configure service:

General Settings:
  Name: Portainer
  URL: http://192.168.1.100:9443
  Icon: Choose from icon library or upload custom

Appearance:
  Category: Container Management (create new if needed)
  Color: Default or custom color
  Show service status: Enabled

Advanced:
  Open in new tab: Enabled (recommended)
  Ping URL: http://192.168.1.100:9443 (for status check)

4. Click Save

5. Service tile appears on dashboard

Service Configuration Options

Basic Settings:

# Example service configuration
{
  "name": "Jellyfin",
  "url": "http://jellyfin.homelab.local:8096",
  "icon": "jellyfin.svg",
  "category": "Media",
  "showHealthCheck": true,
  "healthCheckUrl": "http://jellyfin.homelab.local:8096/health"
}

Icon Options:

Built-in library:
- Search popular apps (Plex, Sonarr, Nextcloud, etc.)
- Automatically sized and themed
Upload custom icons:
- Place in /homarr/icons/
- Use in service: icons/my-icon.png
- Supports PNG, SVG, JPEG
External URLs:
- Direct link to icon
- Must be publicly accessible

Categories for Organization:

Suggested categories:
- Media (Jellyfin, Plex, Emby)
- Downloads (*arr stack, qBittorrent)
- Monitoring (Grafana, Uptime Kuma)
- Infrastructure (Proxmox, Portainer, TrueNAS)
- Home Automation (Home Assistant, Node-RED)
- Network (Pi-hole, AdGuard, OPNsense)
- Tools (VS Code, File Browser)

Adding Multiple Services Quickly

Bulk service addition:

Edit Mode → Import Services
Paste JSON configuration:

[
  {
    "name": "Sonarr",
    "url": "http://192.168.1.100:8989",
    "icon": "sonarr.svg",
    "category": "Media Management"
  },
  {
    "name": "Radarr",
    "url": "http://192.168.1.100:7878",
    "icon": "radarr.svg",
    "category": "Media Management"
  },
  {
    "name": "Prowlarr",
    "url": "http://192.168.1.100:9696",
    "icon": "prowlarr.svg",
    "category": "Media Management"
  }
]

Click Import

Configuring Widgets

Add weather widget:

Edit Mode → Add Widget
Select “Weather”
Configure:

Location:
  City: Your City
  Country: Your Country
  Latitude: 40.7128 (optional but more accurate)
  Longitude: -74.0060

Display Options:
  Temperature Unit: Fahrenheit / Celsius
  Show Forecast: Enabled (shows 5-day forecast)
  Update Interval: 30 minutes

API:
  Provider: OpenWeatherMap (free tier)
  API Key: your-api-key-here

Get OpenWeatherMap API key:

Register at openweathermap.org
Go to API Keys section
Generate new key
Copy and paste into Homarr

Add calendar widget:

Calendar Settings:
  Type: iCal URL
  URL: https://calendar.google.com/calendar/ical/...
  Refresh Interval: 15 minutes

Display:
  Show: 7 days ahead
  Max Events: 10
  Include all-day events: Yes

Supported calendar sources:

Google Calendar (iCal URL)
Nextcloud Calendar
iCloud Calendar
Any CalDAV source

Media Management Widgets

Sonarr/Radarr widget:

Add Widget → Sonarr/Radarr
Configure:

Connection:
  Host: http://sonarr.homelab.local:8989
  API Key: your-sonarr-api-key

Display:
  Show Queue: Yes (displays active downloads)
  Show Upcoming: Yes (shows upcoming episodes)
  Max Items: 5
  Update Interval: 1 minute

Get Sonarr/Radarr API key:

Open Sonarr/Radarr web interface
Settings → General
Copy API Key
Paste into Homarr widget config

Jellyfin/Plex widget:

Connection:
  URL: http://jellyfin.local:8096
  API Key: your-jellyfin-api-key

Display:
  Show Recently Added: Yes
  Item Count: 10
  Media Type: All / Movies / TV Shows

CPU/RAM/Storage widget:

Add Widget → System Stats
Configure:

Monitoring:
  CPU Usage: Enabled
  Memory Usage: Enabled
  Disk Usage: Enabled
  Network Traffic: Enabled

Display:
  Update Interval: 5 seconds
  Show Percentages: Yes
  Show Graphs: Yes (historical data)
  Alert Thresholds:
    CPU: >80%
    Memory: >90%
    Disk: >85%

For accurate stats, ensure Docker socket mounted:

# In docker-compose.yml
volumes:
  - /var/run/docker.sock:/var/run/docker.sock:ro

Docker Integration

Enabling Docker Management

Requirements:

# docker-compose.yml - MUST include:
volumes:
  - /var/run/docker.sock:/var/run/docker.sock:ro

Enable in Homarr:

Settings → Integrations
Docker → Enable
Docker Socket Path: /var/run/docker.sock
Save

Add Docker widget:

Add Widget → Docker
View:
- Running containers
- Stopped containers
- Container status (healthy/unhealthy)
- Resource usage per container

Container Actions:

Start: Click start icon on stopped container
Stop: Click stop icon on running container
Restart: Click restart icon
View Logs: Click logs icon (opens modal with recent logs)
Stats: View CPU/RAM usage per container

Container Filters:

Display Options:
  Show: Running only / All / Stopped only
  Sort By: Name / Status / CPU / Memory
  Search: Filter by container name

Docker Compose Stack Management

View and manage stacks:

Docker Widget → Stacks Tab

Actions per stack:
- View all services in stack
- Stop entire stack
- Restart entire stack
- View combined logs

Customization and Theming

Built-in Themes

Available themes:

Default Light: Clean light theme
Default Dark: Comfortable dark theme
Nord: Popular Nord color palette
Dracula: High-contrast purple theme
Catppuccin: Soothing pastel theme

Change theme:

Settings → Appearance → Theme → Select → Save

Custom Themes

Create custom theme:

Settings → Appearance → Custom Theme
Configure colors:

Primary Color: #3B82F6
Background Color: #1F2937
Card Background: #374151
Text Color: #F9FAFB
Accent Color: #10B981

Font:
  Family: 'Inter', sans-serif
  Size: 14px

Preview changes live
Save custom theme

Custom CSS

Advanced styling:

Settings → Advanced → Custom CSS

/* Example: Larger service tiles */
.service-tile {
  min-height: 140px;
  font-size: 16px;
}

/* Custom category colors */
.category-media {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

/* Transparent widgets */
.widget-container {
  background: rgba(255, 255, 255, 0.1);
  backdrop-filter: blur(10px);
}

/* Custom animations */
.service-tile:hover {
  transform: scale(1.05);
  transition: transform 0.2s ease;
}

Layout Customization

Grid settings:

Settings → Layout

Columns (Desktop): 6
Columns (Tablet): 4
Columns (Mobile): 2

Gap: 16px
Padding: 20px

Service Tile Size:
  Width: 1 column (default) or 2 columns (wide)
  Height: 1 row (default) or 2 rows (tall)

Create widget layouts:

Example layout:
┌─────────┬─────────┬─────────┐
│ Weather │ Calendar│ Docker  │
│ Widget  │ Widget  │ Widget  │
├─────────┴─────────┴─────────┤
│        Service Tiles        │
│  [Plex] [Sonarr] [Radarr]  │
└─────────────────────────────┘

Authentication and User Management

Enabling Authentication

Create user accounts:

Settings → Users
Click Add User
Configure:

Username: john
Password: secure-password
Role: User / Admin
Permissions:
  - View Dashboard: Yes
  - Edit Dashboard: Admin only
  - Manage Docker: Admin only
  - Access Settings: Admin only

Save user

User-Specific Dashboards

Per-user layouts:

Each user can have unique:

Service tiles
Widgets
Theme
Layout

Setup:

Login as specific user
Edit Mode → Customize dashboard
Changes save per-user automatically

Guest Access

Enable guest/anonymous access:

Settings → Security → Guest Access

Guest Access: Enabled
Guest Permissions:
  - View Services: Yes
  - Edit Dashboard: No
  - Docker Management: No

Useful for family members who need quick access to services.

Advanced Features

Search Functionality

Global search:

Click search icon (or press /)
Type service name
Results filter in real-time
Press Enter to open service

Search includes:

Service names
Service URLs
Categories
Tags

Backup and Restore

Backup configuration:

Settings → Backup

# Backup includes:
- Service configurations
- Widget settings
- Theme customizations
- User accounts

# Click "Download Backup"
# Saves homarr-backup-2025-12-16.json

Restore from backup:

Settings → Restore → Upload backup file → Confirm

API Integration

Homarr REST API:

# Get all services
curl http://homarr.local:7575/api/services

# Add service via API
curl -X POST http://homarr.local:7575/api/services   -H "Content-Type: application/json"   -d '{
    "name": "New Service",
    "url": "http://example.com",
    "icon": "example.svg",
    "category": "Tools"
  }'

# Get Docker containers
curl http://homarr.local:7575/api/docker/containers

API authentication:

Generate API token: Settings → API → Create Token

# Use with requests
curl -H "Authorization: Bearer your-api-token"   http://homarr.local:7575/api/services

Integration with Home Assistant

Add Homarr service to Home Assistant:

# configuration.yaml
rest_command:
  homarr_service_check:
    url: "http://homarr.local:7575/api/services/status"
    method: GET

sensor:
  - platform: rest
    resource: http://homarr.local:7575/api/docker/stats
    name: Homarr Docker Stats
    value_template: "{{ value_json.containers | length }}"

Embed Homarr in Home Assistant dashboard:

# Lovelace card
type: iframe
url: http://homarr.local:7575
aspect_ratio: 16:9

Real-World Dashboard Layouts

Media-Focused Dashboard

Layout:
┌──────────┬──────────┬──────────┐
│ Jellyfin │ Sonarr   │ Radarr   │
│ Widget   │ Queue    │ Queue    │
├──────────┴──────────┴──────────┤
│        Media Services           │
│ [Jellyfin] [Plex] [Overseerr]  │
├─────────────────────────────────┤
│      Download Clients           │
│ [qBittorrent] [NZBGet]         │
└─────────────────────────────────┘

Widgets:
- Jellyfin: Recently added movies/shows
- Sonarr: Upcoming episodes
- Radarr: Movie queue

Infrastructure Dashboard

Layout:
┌──────────┬──────────┬──────────┐
│ System   │ Docker   │ Weather  │
│ Stats    │ Status   │          │
├──────────┴──────────┴──────────┤
│    Infrastructure Services      │
│ [Proxmox] [Portainer] [TrueNAS]│
├─────────────────────────────────┤
│      Monitoring Tools           │
│ [Grafana] [Uptime Kuma]        │
└─────────────────────────────────┘

Home Automation Dashboard

Layout:
┌──────────┬──────────┬──────────┐
│ Home     │ Calendar │ Weather  │
│ Assistant│ Events   │ Forecast │
├──────────┴──────────┴──────────┤
│    Automation Services          │
│ [HA] [Node-RED] [Zigbee2MQTT]  │
├─────────────────────────────────┤
│        Smart Devices            │
│ [Lights] [Climate] [Security]  │
└─────────────────────────────────┘

Troubleshooting Common Issues

Services Not Showing Health Status

Symptom: Service tiles always show “Unknown” status

Solutions:

# 1. Verify ping URL is correct
Service Settings → Advanced → Ping URL
Should be: http://service:port (reachable from Homarr container)

# 2. If service requires auth, disable health check or use public endpoint
# 3. Check Homarr logs
docker logs homarr | grep -i health

Docker Integration Not Working

Symptom: Docker widget shows no containers

Solutions:

# 1. Verify socket mounted
docker exec homarr ls -la /var/run/docker.sock

# 2. Check permissions
docker exec homarr test -w /var/run/docker.sock && echo "Writable"

# 3. Restart Homarr
docker-compose restart homarr

Icons Not Loading

Symptom: Service tiles show broken icon images

Solutions:

# 1. Check icon exists
ls -la ~/homarr/homarr/icons/

# 2. Verify volume mount
docker inspect homarr | grep icons

# 3. Use built-in icon library instead
Service Settings → Icon → Search library

Performance Issues with Many Services

Symptom: Dashboard loads slowly with 50+ services

Solutions:

# 1. Disable health checks for some services
# 2. Increase health check interval
Settings → General → Health Check Interval: 60 seconds

# 3. Reduce Docker widget update frequency
Docker Widget → Update Interval: 10 seconds

# 4. Disable unused widgets

Deployment Behind Reverse Proxy

Nginx Configuration

server {
    listen 443 ssl;
    server_name homarr.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://homarr:7575;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Caddy Configuration

homarr.yourdomain.com {
    reverse_proxy homarr:7575
}

Update Base URL in Homarr

Settings → General → Base URL: https://homarr.yourdomain.com

Conclusion and Next Steps

Homarr transforms your homelab into a beautiful, functional dashboard with advanced features that go far beyond static links. You’ve learned:

Installing and configuring Homarr
Creating service tiles with health monitoring
Adding interactive widgets
Managing Docker containers from the dashboard
Customizing themes and layouts
Setting up authentication and multi-user access

Key Takeaways

Beautiful and functional - aesthetics meet utility
Docker integration - manage containers visually
Live monitoring - real-time service health
Customizable - themes, layouts, widgets
User-friendly - intuitive for family and guests

Recommended Next Steps

Deploy Homarr and add your existing services
Configure widgets for weather, calendar, media
Enable Docker integration for container management
Customize theme to match your preferences
Share with family - create guest accounts

Dashy - Alternative dashboard with different focus
Homepage - Simpler bookmark-style dashboard
Portainer - Advanced Docker management
Home Assistant - Home automation integration

Resources

Official Documentation: homarr.dev/docs
GitHub: github.com/ajnart/homarr
Discord Community: discord.gg/homarr
Demo: demo.homarr.dev

Document Version: 1.0 Last Updated: December 16, 2025 Based on: Homarr 0.14+ Estimated Completion Time: 45 minutes

Happy dashboarding!

Overview

Prerequisites

Understanding Homarr’s Philosophy

What Makes Homarr Different

Core Features

Installation with Docker Compose

Basic Installation

First-Time Setup

Creating Service Tiles

Adding Your First Service

Service Configuration Options

Adding Multiple Services Quickly

Configuring Widgets

Weather Widget

Calendar Widget

Media Management Widgets

System Stats Widget

Docker Integration

Enabling Docker Management

Docker Widget Features

Docker Compose Stack Management

Customization and Theming

Built-in Themes

Custom Themes

Custom CSS

Layout Customization

Authentication and User Management

Enabling Authentication

User-Specific Dashboards

Guest Access

Advanced Features

Search Functionality

Backup and Restore

API Integration

Integration with Home Assistant

Real-World Dashboard Layouts

Media-Focused Dashboard

Infrastructure Dashboard

Home Automation Dashboard

Troubleshooting Common Issues

Services Not Showing Health Status

Docker Integration Not Working

Icons Not Loading

Performance Issues with Many Services

Deployment Behind Reverse Proxy

Nginx Configuration

Caddy Configuration

Update Base URL in Homarr

Conclusion and Next Steps

Key Takeaways

Recommended Next Steps

Related Guides

Resources