# Homarr Modern Dashboard

> Homarr dashboard with service integrations.

- Category: Home Lab & Self-Hosting
- Difficulty: beginner
- Components: homarr, nginx
- Tags: dashboard, homarr, homelab, widgets
- Source: https://docker.recipes/homelab/homarr-dashboard-stack

## Overview

Homarr is a modern, customizable dashboard application designed specifically for homelab enthusiasts and self-hosted service management. Built with a sleek, responsive interface, Homarr allows users to create personalized dashboards that aggregate and monitor various self-hosted applications, services, and system metrics through an intuitive drag-and-drop configuration system. The application excels at integrating with popular homelab services like Plex, Sonarr, Radarr, and other *arr applications, providing real-time status updates, system health monitoring, and quick access to frequently used tools. This deployment pairs Homarr with NGINX to create a robust dashboard solution where NGINX serves as a high-performance reverse proxy, handling SSL termination, static file serving, and load distribution. The combination leverages NGINX's event-driven architecture to efficiently manage concurrent dashboard requests while Homarr focuses on service integration and widget rendering. This stack is ideal for homelab administrators, self-hosting enthusiasts, and anyone managing multiple containerized services who needs a centralized, visually appealing interface to monitor and control their infrastructure from a single location.

## Features

- Drag-and-drop dashboard builder with customizable widgets and layouts
- Native integration with *arr applications (Sonarr, Radarr, Lidarr) for media management monitoring
- Docker container discovery and management through mounted Docker socket
- Real-time service status monitoring with health checks and uptime tracking
- Customizable icon library with support for custom service icons
- NGINX reverse proxy with HTTP/2 support for optimized dashboard loading
- Responsive design optimizing dashboard viewing across desktop and mobile devices
- Widget-based architecture supporting system metrics, weather, calendar, and RSS feeds

## Use cases

- Homelab enthusiasts centralizing access to self-hosted media servers, download clients, and automation tools
- IT administrators monitoring containerized application health and performance across development environments
- Home automation enthusiasts integrating smart home controls with media management and system monitoring
- Small business owners managing multiple web services and applications from a unified interface
- Docker enthusiasts organizing and monitoring their container ecosystem with visual service management
- Network administrators creating status dashboards for internal services and infrastructure monitoring
- Self-hosting advocates replacing cloud-based dashboards with locally-controlled service aggregation

## Prerequisites

- Docker Engine and Docker Compose installed on the host system
- Minimum 512MB RAM available for Homarr application and widget rendering
- Docker socket access permissions for container discovery and management features
- Network ports 7575 and 80 available for Homarr and NGINX services respectively
- Basic understanding of Docker volume management for persistent dashboard configurations
- NGINX configuration knowledge for customizing reverse proxy settings and SSL setup

## docker-compose.yml

```yaml
services:
  homarr:
    image: ghcr.io/ajnart/homarr:latest
    container_name: homarr
    restart: unless-stopped
    ports:
      - "${HOMARR_PORT:-7575}:7575"
    environment:
      - TZ=${TZ:-UTC}
    volumes:
      - homarr_configs:/app/data/configs
      - homarr_icons:/app/public/icons
      - /var/run/docker.sock:/var/run/docker.sock:ro

  nginx:
    image: nginx:alpine
    container_name: homarr-nginx
    restart: unless-stopped
    ports:
      - "${NGINX_PORT:-80}:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro

volumes:
  homarr_configs:
  homarr_icons:
```

## .env

```bash
# Homarr
HOMARR_PORT=7575
TZ=UTC
NGINX_PORT=80
```

## Usage notes

- Homarr at http://localhost:7575
- Drag-and-drop configuration
- Docker socket for containers
- Integrates with *arr apps

## Troubleshooting

- Homarr widgets showing 'Service Unavailable': Verify target service URLs are accessible from within Docker network and check firewall rules
- Docker containers not appearing in Homarr: Ensure Docker socket is properly mounted with read permissions and check container labels for service discovery
- Dashboard configuration lost after restart: Verify homarr_configs volume is properly mounted and has write permissions for the container user
- NGINX showing 502 Bad Gateway: Check Homarr container status and ensure port 7575 is accessible between containers in the same Docker network
- *arr application integration failing: Verify API keys are correctly configured and the applications are accessible on their specified ports
- Custom icons not displaying: Ensure homarr_icons volume is mounted and icon files are placed in the correct directory structure within the volume

